Log inSubmit server
MCP Ephemeris logo

MCP Ephemeris

Computes planetary positions, charts, transits, eclipses, and related astrology data through 19 MCP tools.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install MCP Ephemeris

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "mcp-ephemeris": {
      "command": "npx",
      "args": [
        "-y",
        "@cosmosos/mcp-ephemeris"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Automated check passed— started and listed 19 tools correctly (4d ago).

Overview

The mcp-ephemeris MCP server provides computed planetary positions, moon phases, charts, transits, eclipses, and numerology through 19 MCP tools. It uses Swiss Ephemeris by default when its native addon can compile, with an automatic AstraCore TypeScript fallback. The server runs locally and sends data externally only when validating positions against NASA's JPL Horizons API. Reach for it when an agent needs reproducible astronomical or astrology calculations instead of generating positions itself.

Use cases

  • Calculate natal charts from birth data
  • Check planetary transits and aspects
  • Find upcoming eclipses and retrograde windows
  • Compare positions with JPL Horizons
  • Generate astrocartography lines

Key features

  • 19 astrology and ephemeris tools
  • Swiss Ephemeris with AstraCore fallback
  • Natal, synastry, composite, and return charts
  • Ingress, retrograde, and eclipse calculations
  • Optional JPL Horizons validation
  • Local processing of birth data

Tools19

What MCP Ephemeris lets your agent do. Expand a tool for its parameters.

Verified live~3.7k tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked Today

Recent health check succeeded.

8/8 checks healthy over the last 42d

What it can do

From the 19 tools this server returned when we ran it.

Read-only tools · 19
Network at startup3 connections
Files written at startupNone
Install scriptsNone
npm provenanceNot published
Package age91 days
Maintainers1

Observed 2026-10-20 in an isolated sandbox. A description of reach, not a security audit.

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 14d ago via OSV.dev · @cosmosos/mcp-ephemeris (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

npm downloads180Package downloads in the last 30 days.
Last commit3mo agoMost recent push to the default branch.
Availability100%Our rolling endpoint + install checks that succeeded.
Install checkPassedOur sandbox started it and listed its tools.
Tools exposed19Callable tools this server registers over MCP.
Directory activity1 viewsConfig copies, upvotes, and views on AllMCPs.

How MCP Ephemeris works

What the mcp-ephemeris MCP server does

The mcp-ephemeris MCP server exposes 19 tools for calculating and inspecting planetary and astrology data. It covers ecliptic positions, moon phases, current sky conditions for a location, major and minor aspects, natal charts, relationship charts, returns, progressions, ingresses, retrograde periods, eclipses, astrocartography, and life-path numerology.

Chart-oriented tools accept birth information and, where relevant, a date, place, zodiac mode, or house system. The returned data can include houses, aspects, angles such as the Ascendant and Midheaven, moon phase information, Hermetic Lots, or relationship summaries. Event tools identify sign changes, station dates, eclipse contacts, and other time-based results.

How it works

The MCP server acts as a calculation layer between an AI client and an ephemeris engine. The model requests a tool result and interprets the returned values; it is not expected to calculate planetary positions itself.

Swiss Ephemeris is the default engine when the native addon builds successfully. The project reports sub-arcsecond comparisons with JPL Horizons for selected bodies, and the validate_against_horizons tool can measure differences in arcseconds. That validation call requires network access to NASA's public API.

If the native addon cannot compile, the server falls back to AstraCore, a pure-TypeScript engine based on VSOP/Meeus methods. Sun and Moon calculations remain accurate under that fallback, while outer-planet positions can differ by a few arcminutes. The get_engine_diagnostic tool reports the active engine, native-addon status, and effective precision.

Setup and configuration

The mcp-ephemeris MCP server requires Node.js 20 or newer. For the default Swiss Ephemeris path, the host should also have Python 3, Make, and a C++ compiler so the native addon can build. Without that toolchain, the server can use AstraCore automatically.

For Claude Desktop, add an MCP entry that runs npx -y @cosmosos/mcp-ephemeris, then fully quit and relaunch the application. The README gives the same stdio command pattern for Cursor, Windsurf, and other MCP clients. Local development can use pnpm install, pnpm build, and pnpm start.

Set ASTRO_ENGINE=swisseph to require Swiss Ephemeris or ASTRO_ENGINE=astracore to select the pure-TypeScript engine explicitly. No environment variable is required for the default startup behavior.

Tools and capabilities

The mcp-ephemeris MCP server groups its tools into several practical areas:

  • Query positions, moon illumination, current transits, and aspect grids.
  • Build natal, synastry, composite, solar-return, and lunar-return charts.
  • Calculate secondary progressions and transit-to-natal aspects sorted by orb.
  • Find ingresses, retrograde/direct stations, and eclipse details or upcoming eclipses.
  • Produce planetary MC/IC lines and parans for astrocartography.
  • Calculate a life-path number and inspect engine diagnostics.
  • Compare calculated positions with JPL Horizons when network access is available.

Eclipse tools that depend on the native Swiss Ephemeris addon return null when AstraCore is active.

Limitations and notes

The server is free for non-commercial use under PolyForm Noncommercial 1.0.0. Commercial or professional use requires a paid license. The optional Swiss Ephemeris dependency has separate AGPL or commercial licensing requirements.

Birth data stays on the local machine during normal operation. The Horizons comparison is the exception because it sends a request to NASA's public API. Precision also depends on the selected engine: Swiss Ephemeris supports the documented high-precision comparisons, while the fallback can introduce larger differences for outer planets.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about MCP Ephemeris

mcp-ephemeris is an MCP server that connects AI clients to Swiss Ephemeris or its AstraCore fallback for computed sky data. Its main tools return planetary positions, moon phases, natal charts, transits, aspects, eclipses, returns, progressions, astrocartography, and optional JPL Horizons validation.

Install it by adding `npx -y @cosmosos/mcp-ephemeris` as a stdio MCP command in your client configuration. Claude Desktop uses Settings → Developer → Edit Config; the README provides the same command pattern for Cursor, Windsurf, and other MCP clients.

Yes, mcp-ephemeris works with Cursor through the documented stdio configuration. Add an MCP server entry using the `npx` command and `-y @cosmosos/mcp-ephemeris` argument, then use Cursor to call the exposed tools.

The server automatically falls back to AstraCore when the Swiss Ephemeris native addon cannot compile. AstraCore is a pure-TypeScript engine with no native binary; Sun and Moon remain accurate, while outer planets may drift by a few arcminutes.

No, normal calculations run on your machine and do not send birth data elsewhere. Only `validate_against_horizons` makes an outbound request, contacting NASA's public JPL Horizons API to compare calculated positions.

Related MCP servers

All in Aerospace & Astrodynamics All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewMCP Ephemeris AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/mcp-ephemeris?style=directory)](https://allmcps.com/mcp/mcp-ephemeris)
HTML Embed
<a href="https://allmcps.com/mcp/mcp-ephemeris"><img src="https://allmcps.com/api/badge/mcp-ephemeris?style=directory" alt="MCP Ephemeris on AllMCPs" /></a>