@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.
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
pnpm build
pnpm start
- 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.