The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the MCP Ephemeris listing page.
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)
Open Settings → Developer → Edit Config, then add:
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.
19 tools, all backed by the same server-side computed engine.
| 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 |
| 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 |
| 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) |
| 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.
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.
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.
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).
swisseph): a C++ build chain (python3, make, a
compiler) on the machine. Otherwise, automatic fallback to astracore, with
no configuration.Powered by the astrology engine of Llmastro. Learn more about the precision and architecture: https://llmastro.com/notre-moteur.
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.
This repository is self-contained: the ephemeris engine is vendored in
vendor/ephemeris/ (source), and the build inlines it into dist/ via
tsup.
swisseph (sub-arcsecond precision) if the native addon
compiles, otherwise automatic fallback to astracore (pure TypeScript, no
binary). Force via ASTRO_ENGINE=swisseph|astracore.@astro-platform/ephemeris (Llmastro),
re-synced manually.