{
  "markdown": "# @cosmosos/mcp-ephemeris\n\n**The real sky, for your AI.** An [MCP](https://modelcontextprotocol.io) server\nthat gives any assistant (Claude, Cursor, agents) **computed planetary\npositions** — never guessed — powered by the\n[Swiss Ephemeris](https://www.astro.com/swisseph/) engine, and **validated\nagainst JPL Horizons (NASA)** to under one arcsecond.\n\n> **Cardinal rule: the LLM never computes.** This server is a facade over an\n> ephemeris engine. The model interprets; the sky is a fact.\n\n*(Version française : <https://llmastro.com/notre-moteur>)*\n\n## Quick start (Claude Desktop)\n\nOpen **Settings → Developer → Edit Config**, then add:\n\n```json\n{\n  \"mcpServers\": {\n    \"llmastro\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@cosmosos/mcp-ephemeris\"]\n    }\n  }\n}\n```\n\nFully quit Claude Desktop (system tray) and relaunch it. Then ask:\n*\"What's the moon phase today?\"* — Claude calls the server and answers from\ngenuinely computed positions.\n\n**Cursor / Windsurf / others**: add the same `llmastro` entry\n(`command: npx`, `args: [\"-y\", \"@cosmosos/mcp-ephemeris\"]`) to your client's MCP\nconfiguration.\n\n## Tools exposed\n\n**19 tools**, all backed by the same server-side computed engine.\n\n### Positions & sky\n| Tool | Input | Output |\n|---|---|---|\n| `get_planet_positions` | `datetime` (ISO UTC) | ecliptic positions of all bodies (sign, degree, retro) |\n| `get_moon_phase` | `datetime` (ISO UTC) | moon phase, illumination %, description |\n| `get_current_sky` | `latitude`, `longitude` | the sky right now (current transits) for a place |\n| `get_aspects` | `datetime` (ISO UTC) | grid of major + minor aspects between bodies |\n\n### Natal chart & relationships\n| Tool | Input | Output |\n|---|---|---|\n| `get_natal_chart` | birth + `zodiac` (tropical/sidereal), `houseSystem` (7 systems) | full chart: houses, aspects, ASC/MC, moon phase, Hermetic Lots |\n| `get_transits` | birth + optional `datetime` | transit→natal aspects, sorted by orb |\n| `get_synastry` | two births | inter-chart aspects + harmony/tension summary |\n| `get_composite_chart` | two births | midpoint composite chart |\n| `get_secondary_progressions` | birth + `targetDate` | progressed positions (\"a day for a year\") |\n| `get_solar_return` | birth + `year` (+ optional place) | instant + chart of the solar return |\n| `get_lunar_return` | birth + optional `after` | instant + chart of the next lunar return |\n\n### Celestial events\n| Tool | Input | Output |\n|---|---|---|\n| `get_ingresses` | `body`, `start`, `end` | sign-change dates (retrograde-robust) |\n| `get_retrograde_windows` | `body`, `start`, `end` | retrograde/direct stations over the range |\n| `get_eclipse_details` | `datetime`, `kind` | magnitude, obscuration, Saros of a known eclipse *(swisseph)* |\n| `get_next_eclipse` | `from`, `kind`, optional `backward` | next/previous eclipse: maximum, type, contacts *(swisseph)* |\n\n### Astrocartography, numerology, authority\n| Tool | Input | Output |\n|---|---|---|\n| `get_astrocartography` | `datetime` (ISO UTC) | planetary MC/IC lines + parans (crossings) |\n| `get_life_path` | `date` (YYYY-MM-DD) | life-path number (numerology) |\n| `get_engine_diagnostic` | — | active engine, native addon load status, real precision |\n| `validate_against_horizons` | `datetime`, optional `bodies` | delta of our positions vs JPL Horizons (NASA) in arcseconds — network required |\n\n*(swisseph)* = requires the native Swiss Ephemeris addon; returns `null` on the AstraCore fallback.\n\n## Precision\n\nUnder [Swiss Ephemeris](https://www.astro.com/swisseph/), positions match the\nworld reference **JPL Horizons (NASA)** to under one arcsecond (measured\n2026-07-19):\n\n| Body | Difference vs NASA |\n|---|---|\n| Sun | 0.2″ |\n| Moon | 1.5″ |\n| Jupiter | 0.1″ |\n| Pluto | 0.4″ |\n\nCheck it yourself with the `validate_against_horizons` tool.\n\n## Two engines\n\nComputation is routed by the `ASTRO_ENGINE` variable:\n\n- **`swisseph`** (default) — Swiss Ephemeris, native addon, sub-arcsecond\n  precision. Compiles automatically wherever a C++ build chain is present\n  (Linux, macOS, most servers).\n- **`astracore`** — in-house pure-TypeScript engine (VSOP/Meeus), **no native\n  binary**. Used as an automatic fallback when `swisseph` couldn't be compiled\n  (common on Windows). Sun and Moon stay accurate; outer planets drift by a few\n  arcminutes.\n\nTo force an engine: `ASTRO_ENGINE=swisseph` or `ASTRO_ENGINE=astracore`.\n\n## Privacy\n\nThe server runs **on your machine**: your birth data is sent nowhere. Only\n`validate_against_horizons` makes an outbound request (to NASA's public API).\n\n## Requirements\n\n- Node.js ≥ 20.\n- For maximum precision (`swisseph`): a C++ build chain (`python3`, `make`, a\n  compiler) on the machine. Otherwise, automatic fallback to `astracore`, with\n  no configuration.\n\n## About\n\nPowered by the astrology engine of [Llmastro](https://llmastro.com). Learn more\nabout the precision and architecture: <https://llmastro.com/notre-moteur>.\n\n## License\n\n**Free for non-commercial use** (personal, research, education, non-profit\norganizations) — under the\n[PolyForm Noncommercial 1.0.0](./LICENSE) license.\n\n**Commercial / professional use: a paid license is required.** To obtain one,\ncontact KAIROSAST LTD via <https://llmastro.com/contact>.\n\nNote: the optional `swisseph` dependency (Swiss Ephemeris, Astrodienst) has its\nown license (AGPL or a commercial Swiss Ephemeris license) and is not covered by\nthis one. Professional use must comply with it separately.\n\n## Development\n\nThis repository is **self-contained**: the ephemeris engine is vendored in\n`vendor/ephemeris/` (source), and the build inlines it into `dist/` via\n[`tsup`](https://tsup.egoist.dev/).\n\n```bash\npnpm install          # or npm install\npnpm build            # bundles dist/index.js (engine inlined)\npnpm start            # runs the MCP server (stdio) locally\n```\n\n- Default engine: `swisseph` (sub-arcsecond precision) if the native addon\n  compiles, otherwise automatic fallback to `astracore` (pure TypeScript, no\n  binary). Force via `ASTRO_ENGINE=swisseph|astracore`.\n- The vendored engine is a snapshot of `@astro-platform/ephemeris` (Llmastro),\n  re-synced manually.\n",
  "bytes": 6132,
  "sha": "a54a02808e80039bad4d8c3d92831a5f8f4a021eec4d396e7dc18bda3aaeec0b",
  "repo_slug": "kairosastro-sketch/mcp-ephemeris",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_kairosastro_sketch_mcp_ephemer_2ad1efed/readme"
}