Mcp Ephemeris

io.github.kairosastro-sketchPublished by GitHub account kairosastro-sketchv0.2.3Updated Oct 24, 2026

NASA-validated computed planetary positions for your AI: 19 astrology tools, never hallucinated.

VerifiedSTDIODesktop onlyLocation & Lifestyle Data & Analytics

Server details

Identifier: io.github.kairosastro-sketch/mcp-ephemeris
Transport: STDIO
Runtime: Desktop only
Trust: Verified
Published: Sep 16, 2026

Security note

MCP servers receive tool arguments from a conversation and may perform external actions. Review what a server can do before you enable it, and give it only the access it needs.

The registry verified the GitHub account kairosastro-sketch for this listing. That does not show the account is the product's maker.

SourceWeft's checks cover whether the listing is complete and the endpoint answered; they do not review the server's code or what its tools do.

Add a badge to your README

Show readers this MCP server is listed on SourceWeft. The badge links to this page.

[![Listed on SourceWeft](https://sourceweft.com/badge/mcp/io.github.kairosastro-sketch%2Fmcp-ephemeris.svg)](https://sourceweft.com/mcp/io.github.kairosastro-sketch%2Fmcp-ephemeris?utm_source=readme&utm_medium=badge)

Overview

AI-generated overview

A local MCP server that gives an assistant computed astrological ephemeris data — planetary positions, natal charts, transits and eclipses — from a Swiss Epheme

What you can do: Compute sky positions: planetary ecliptic positions, moon phase and illumination, current transits for a place, and aspect grids for a date and time. Build natal and relationship charts: full natal charts with houses and lots, transits to a birth chart, synastry, composite charts, secondary progressions, and solar and lunar returns. Find celestial events: sign ingresses, retrograde windows, and eclipse details or the next or previous eclipse. Produce astrocartography lines and parans, and a numerology life-path number. Check the engine and compare computed positions against NASA JPL Horizons.
When to use it: Useful when you want an assistant to answer astrology questions from computed positions rather than guesses — natal charts, transits, returns, eclipses, astrocartography — or to verify the engine's accuracy against NASA reference data.
Requirements: Runs locally over stdio via npx, so Node.js 20 or newer is needed. Maximum precision needs a C++ build chain (python3, make, a compiler) to compile the Swiss Ephemeris addon; otherwise it falls back automatically to a pure-TypeScript engine. The ASTRO_ENGINE variable can force either engine. The NASA comparison tool needs network access.

Before you install

Birth data stays on the machine except when the NASA comparison tool is used, which makes an outbound request to NASA's public API. The fallback engine is less precise for outer planets. Installing pulls an npm package that may compile native code on first run.

Installation

In SourceWeft

Open Mcp Ephemeris in the dashboard and add it to a workspace.
Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

@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:

json

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

{  "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):

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.

bash

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

pnpm install          # or npm installpnpm 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.

Source: README.md at commit ba8d1b4

Tools

SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

v0.2.3LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
DescriptionRequired15 pts
Logo10 pts
Documentation15 pts
License10 pts
Declare a license in the repository or the registry entry.

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