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-four 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-four tools. Ask it to enumerate them, or check the client's MCP panel:

natal_chart, current_sky, 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), transits, synastry, find_aspect_dates, rectification_grid, sky_events (rise/set, phases, stations, zodiac crossings, solar and lunar eclipses), planetary_hours, void_of_course, returns (solar/lunar return instants plus the first return chart), progressions (secondary progressions and solar-arc directions), composite (midpoint composite and the Davison chart), dignities (essential dignity and sect for the seven traditional planets), lots (the seven Hermetic lots, sect-aware), 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), nakshatras (lunar mansions, padas, and lords), dasha (Vimshottari, Yogini, or Ashtottari periods), vargas (Parashari divisional charts), yogas (Pancha Mahapurusha, raja/dhana yogas, and yogakarakas), 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), similar_skies (when the sky most resembled a reference moment, by cosine similarity 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), chart_facts (the chart's validated facts as ranked, citable atoms — placements through yogas, including transits/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), synastry (inter-chart aspects, house overlays, composite midpoint atoms, and the same ranked facts + brief as chart_facts), and counterfactual_chart (a birth chart perturbed: shift time, move place, or splice body longitudes, with a legible diff of sign/house/aspect changes vs the original).

sky_events also reports eclipse geography: the sub-solar point of greatest eclipse, the path-of-totality width, and, given a place, local circumstances.

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-four, 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.