@cosmosos/mcp-ephemeris

The real sky, for your AI. An MCP server that gives any assistant (Claude, Cursor, agents) computed planetary positions — never guessed — powered by the Swiss Ephemeris engine, and validated against JPL Horizons (NASA) to under one arcsecond.

Cardinal rule: the LLM never computes. This server is a facade over an ephemeris engine. The model interprets; the sky is a fact.

(Version française : https://llmastro.com/notre-moteur)

Quick start (Claude Desktop)

Open Settings → Developer → Edit Config, then add:

{
  "mcpServers": {
    "llmastro": {
      "command": "npx",
      "args": ["-y", "@cosmosos/mcp-ephemeris"]
    }
  }
}

Fully quit Claude Desktop (system tray) and relaunch it. Then ask: "What's the moon phase today?" — Claude calls the server and answers from genuinely computed positions.

Cursor / Windsurf / others: add the same llmastro entry (command: npx, args: ["-y", "@cosmosos/mcp-ephemeris"]) to your client's MCP configuration.

Tools exposed

19 tools, all backed by the same server-side computed engine.

Positions & sky

Tool	Input	Output
`get_planet_positions`	`datetime` (ISO UTC)	ecliptic positions of all bodies (sign, degree, retro)
`get_moon_phase`	`datetime` (ISO UTC)	moon phase, illumination %, description
`get_current_sky`	`latitude`, `longitude`	the sky right now (current transits) for a place
`get_aspects`	`datetime` (ISO UTC)	grid of major + minor aspects between bodies

Natal chart & relationships

Tool	Input	Output
`get_natal_chart`	birth + `zodiac` (tropical/sidereal), `houseSystem` (7 systems)	full chart: houses, aspects, ASC/MC, moon phase, Hermetic Lots
`get_transits`	birth + optional `datetime`	transit→natal aspects, sorted by orb
`get_synastry`	two births	inter-chart aspects + harmony/tension summary
`get_composite_chart`	two births	midpoint composite chart
`get_secondary_progressions`	birth + `targetDate`	progressed positions ("a day for a year")
`get_solar_return`	birth + `year` (+ optional place)	instant + chart of the solar return
`get_lunar_return`	birth + optional `after`	instant + chart of the next lunar return

Celestial events

Tool	Input	Output
`get_ingresses`	`body`, `start`, `end`	sign-change dates (retrograde-robust)
`get_retrograde_windows`	`body`, `start`, `end`	retrograde/direct stations over the range
`get_eclipse_details`	`datetime`, `kind`	magnitude, obscuration, Saros of a known eclipse (swisseph)
`get_next_eclipse`	`from`, `kind`, optional `backward`	next/previous eclipse: maximum, type, contacts (swisseph)

Astrocartography, numerology, authority

Tool	Input	Output
`get_astrocartography`	`datetime` (ISO UTC)	planetary MC/IC lines + parans (crossings)
`get_life_path`	`date` (YYYY-MM-DD)	life-path number (numerology)
`get_engine_diagnostic`	—	active engine, native addon load status, real precision
`validate_against_horizons`	`datetime`, optional `bodies`	delta of our positions vs JPL Horizons (NASA) in arcseconds — network required

(swisseph) = requires the native Swiss Ephemeris addon; returns null on the AstraCore fallback.

Precision

Under Swiss Ephemeris, positions match the world reference JPL Horizons (NASA) to under one arcsecond (measured 2026-07-19):

Body	Difference vs NASA
Sun	0.2″
Moon	1.5″
Jupiter	0.1″
Pluto	0.4″

Check it yourself with the validate_against_horizons tool.

Two engines

Computation is routed by the ASTRO_ENGINE variable:

swisseph (default) — Swiss Ephemeris, native addon, sub-arcsecond precision. Compiles automatically wherever a C++ build chain is present (Linux, macOS, most servers).
astracore — in-house pure-TypeScript engine (VSOP/Meeus), no native binary. Used as an automatic fallback when swisseph couldn't be compiled (common on Windows). Sun and Moon stay accurate; outer planets drift by a few arcminutes.

To force an engine: ASTRO_ENGINE=swisseph or ASTRO_ENGINE=astracore.

Privacy

The server runs on your machine: your birth data is sent nowhere. Only validate_against_horizons makes an outbound request (to NASA's public API).

Requirements

Node.js ≥ 20.
For maximum precision (swisseph): a C++ build chain (python3, make, a compiler) on the machine. Otherwise, automatic fallback to astracore, with no configuration.

About

Powered by the astrology engine of Llmastro. Learn more about the precision and architecture: https://llmastro.com/notre-moteur.

License

Free for non-commercial use (personal, research, education, non-profit organizations) — under the PolyForm Noncommercial 1.0.0 license.

Commercial / professional use: a paid license is required. To obtain one, contact KAIROSAST LTD via https://llmastro.com/contact.

Note: the optional swisseph dependency (Swiss Ephemeris, Astrodienst) has its own license (AGPL or a commercial Swiss Ephemeris license) and is not covered by this one. Professional use must comply with it separately.

Development

This repository is self-contained: the ephemeris engine is vendored in vendor/ephemeris/ (source), and the build inlines it into dist/ via tsup.

pnpm install          # or npm install
pnpm build            # bundles dist/index.js (engine inlined)
pnpm start            # runs the MCP server (stdio) locally

Default engine: swisseph (sub-arcsecond precision) if the native addon compiles, otherwise automatic fallback to astracore (pure TypeScript, no binary). Force via ASTRO_ENGINE=swisseph|astracore.
The vendored engine is a snapshot of @astro-platform/ephemeris (Llmastro), re-synced manually.

mcp ephemeris