mcp-ephemeris

# @cosmosos/mcp-ephemeris

**The real sky, for your AI.** An [MCP](https://modelcontextprotocol.io) server
that gives any assistant (Claude, Cursor, agents) **computed planetary
positions** — never guessed — powered by the
[Swiss Ephemeris](https://www.astro.com/swisseph/) 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:

```json
{
  "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](https://www.astro.com/swisseph/), 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](https://llmastro.com). 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) 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`](https://tsup.egoist.dev/).

```bash
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.