MCP Setup

caelus-mcp exposes the engine over the Model Context Protocol. Positions are computed by the engine on each call, never recalled from training data, so every answer is deterministic.

There are two ways to connect, with the same thirty-five tools either way:

• Hosted (Streamable HTTP): point your client at https://www.ephemengine.com/api/mcp. Nothing to install.
• Local (stdio): run npx -y caelus-mcp. Best for offline use, version pinning, or air-gapped setups.

Hosted endpoint (no install)

The tools are served over MCP Streamable HTTP at https://www.ephemengine.com/api/mcp. The endpoint is stateless: each request is self-contained, so there is no session to manage. Positions are identical to the stdio server.

{
"mcpServers": {
  "caelus": {
    "url": "https://www.ephemengine.com/api/mcp"
  }
}
}

Run it locally

The published binary runs straight from npm, no global install:

npx -y caelus-mcp

It waits for an MCP client to speak to it over stdio, so an empty terminal is expected. Wire it into a client below instead of running it by hand.

Configure your client

Every client points at the same command (npx -y caelus-mcp); only the config file and key differ.

{
"mcpServers": {
  "caelus": {
    "command": "npx",
    "args": ["-y", "caelus-mcp"]
  }
}
}

Verify the tools appeared

After the client reloads, it should list thirty-five tools. Ask it to enumerate them, or check the client's MCP panel:

Charts and readings

• natal_chart: natal positions, houses, and aspects
• current_sky: the sky at any moment, no birth data needed
• transits: transits to a natal chart over a window
• synastry: inter-chart aspects, house overlays, composite midpoint atoms, and the same ranked facts and brief as chart_facts
• composite: midpoint composite and the Davison chart
• returns: solar/lunar return instants plus the first return chart
• progressions: secondary progressions and solar-arc directions
• counterfactual_chart: a birth chart perturbed (shift time, move place, or splice body longitudes), with a legible diff of sign, house, and aspect changes vs the original

Sky, events, and search

• sky_view: frame the visible sky at a place and moment as a pixel-precise prompt for an AI image model (positions, sizes, magnitudes, Moon phase, twilight, deep star field, the Milky Way, and ecliptic/sign/house/constellation overlays)
• sky_view_sequence: an animation timeline of Sky View frames
• sky_events: rise/set, phases, stations, zodiac crossings, solar and lunar eclipses (also eclipse geography: the sub-solar point of greatest eclipse, path-of-totality width, and local circumstances for a place)
• parans: co-angular bodies over the 24 hours from a date at a latitude; the fixed-star paran relationship, computed for the moving bodies
• find_aspect_dates: when a wanted aspect forms, over a window
• electional_search: rank moments in a window for a set of wanted aspects, optionally avoiding a void-of-course Moon
• cosmic_weather: the day's active configurations, stations, and void-of-course Moon, with no birth chart needed
• similar_skies: when the sky most resembled a reference moment, by cosine similarity over a window

Hellenistic time-lords

• profections: annual and monthly profections, lord of the year
• firdaria: the planetary time-lord periods
• releasing: zodiacal releasing (aphesis) from the Lot of Spirit or Fortune
• directions: primary directions of the planets to the angles, and optionally between the planets
• lots: the seven Hermetic lots, sect-aware

Vedic

• nakshatras: lunar mansions, padas, and lords
• dasha: Vimshottari, Yogini, or Ashtottari periods
• vargas: Parashari divisional charts
• yogas: Pancha Mahapurusha, raja/dhana yogas, and yogakarakas

Analysis and facts

• dignities: essential dignity and sect for the seven traditional planets
• planetary_hours: planetary hours for a moment and place
• void_of_course: void-of-course Moon windows
• rectification_grid: birth-time rectification candidates over a time grid
• aspect_patterns: the classical configurations (T-squares, grand trines and crosses, yods, kites, mystic rectangles, and stelliums) as maximal structured objects
• chart_signature: element, modality, quadrant, and hemisphere distributions, the dominant element, modality, and sign, and the classical chart ruler
• chart_facts: the chart's validated facts as ranked, citable atoms (placements through yogas, including transits and time-lords when target_date is set, fixed-star conjunctions and the Part of Fortune), plus a ready-to-interpret brief; accepts structured when anchors, an in-request anchors registry, realm, target_date, include_vedic, and constraints for archetypal charts (see the Interpretation and Provenance guides)

Synthetic bodies

• synthetic_validate: check an authored synthetic celestial system for ill-defined inputs (duplicate body ids, non-positive periods, out-of-range eccentricity, a dangling observer)
• synthetic_positions: positions of every body in an authored synthetic system at one instant, with speed and retrograde per body
• synthetic_sky_view: Sky View for a mix of real and synthetic bodies, with authored render attributes flowing into the pixel spec and prompt

natal_chart and current_sky also tag each body with its solar phase (cazimi, combust, under the beams) and each aspect as applying or separating, with a normalized strength.

If you see all thirty-five, the server is wired correctly. The server also exposes two resources: caelus://glossary (aspect angles and orbs, signs, bodies, house systems, essential dignities) and caelus://accuracy (the validation table), plus a prompt, rectification_session, a guided flow around rectification_grid and find_aspect_dates.

A natal-chart call returns structured positions, not prose:

{
"utc": "1990-06-10T14:30:00Z",
"houses": "placidus",
"bodies": {
  "sun":  { "lon": 79.45,  "pos": "19°27'Gem", "house": 11, "speed": 0.96 },
  "moon": { "lon": 283.28, "pos": "13°17'Cap", "house": 6,  "speed": 12.19 },
  "saturn": { "lon": 294.31, "pos": "24°18'Cap", "house": 6, "rx": true, "speed": -0.05 }
},
"aspects": [
  { "a": "sun", "b": "moon", "aspect": "quincunx", "orb": 3.8, "phase": "applying", "strength": 0.62 }
]
}

Example prompts

• "Natal chart: born June 10 1990, 2:30pm, Tampa FL."
• "When is Saturn square my natal Moon in the next two years?"
• "Compare my chart with my partner's." (synastry returns citable atoms + brief)
• "Natal chart facts with transits active today." (chart_facts + target_date)
• "Next solar eclipse? Lunar eclipses in 2026?"
• "My solar return chart for this year."
• "Progress my chart to today: secondary positions and the solar arc."
• "Composite and Davison charts for me and my partner."
• "Which of my planets have essential dignity, and are they in sect?"
• "Where are my Lots of Fortune and Spirit?"
• "Who's my lord of the year for 2026?"
• "Which firdaria period am I in right now?"
• "Run my zodiacal releasing from the Lot of Spirit."
• "What are my primary directions to the angles?"
• "Do I have any T-squares, grand trines, or yods in my chart?"
• "What's the elemental and modal balance of my chart, and my chart ruler?"

Troubleshooting

• npx not found / server never starts. GUI clients (Claude Desktop, Cursor) do not inherit your shell PATH, so a node/npx installed via nvm or Homebrew may be invisible. Use the absolute path as command (find it with which npx), or install Node where the client can see it. Node 18+ is required.
• Tools don't show up. Most clients only read MCP config on a full restart. Quit completely (not just close the window) and reopen. Confirm the JSON parses (a trailing comma is the usual culprit).
• First call is slow. npx downloads the package on first run; it is cached afterward. Pinning a version (below) avoids surprise re-downloads.

Version pinning for production

npx -y caelus-mcp always resolves the latest release. Pin an exact version so behaviour is reproducible and the four packages stay in lockstep:

{
"mcpServers": {
  "caelus": {
    "command": "npx",
    "args": ["-y", "caelus-mcp@0.15.0"]
  }
}
}

Agent-oriented docs live at llms.txt. See Architecture for where MCP fits in an end-to-end app.