ephemeris-mcp

Ephemeris MCP

Ephemeris MCP is a standalone Swiss Ephemeris computation service exposed through MCP. v0.2 provides planetary positions, house cusps, lunar state, sidereal time, and related astronomical data to downstream consumers. astro-mcp is the first downstream consumer; others (e.g. satrack-mcp) are planned.

The server binds to 0.0.0.0 and the current reachable instance is 192.168.0.200:7015.

What it is

• A shared Swiss Ephemeris service so downstream servers don't have to bundle it
• Source of planetary positions, house cusps, solar events, lunar state, sidereal time, and constellation lookup
• A convenience moon-phase tool for quick manual checks
• A raw sky-state snapshot tool (get_sky_state) for downstream chart engines
• 22 house systems available for house cusp computation

What it is not

• Not an interpretation engine (no element balance, stelliums, aspect patterns)
• Not a charting service (no aspects, transits, synastry)
• Not a consumer-facing astrology app
• Not a finished satellite tracking stack in v0.2

Project direction

The implementation is intentionally split between:

• Swiss Ephemeris computation as a service (positions, houses, lunar, solar, sidereal)
• Cache-backed retrieval of repeatable results
• A small MCP surface for downstream consumers
• A later satellite slice that will add TLE and pass prediction support

The current design and tool intent are described in:

• initial_idea.md
• IMPLEMENTATION_PLAN.md
• AGENTS.md
• Wiki project page: /home/lucky/wiki/entities/projects/ephemeris-mcp.md

Repo layout

• main.py — uvicorn entry point
• src/ephemeris_mcp/ — application code
• tests/ — automated checks
• run.sh / restart.sh / killserver.sh — service helpers
• Dockerfile / docker-compose.yml — container entry points
• data/ephe/ — Swiss Ephemeris .se1 files (git-tracked, image-bundled)
• data/cache/ — runtime sqlite cache (gitignored, volume-mounted)
• logs/ — runtime logs

mcporter Examples

Use the repo's configured MCP client pattern:

mcporter --config "$CONFIG" list ephemeris

Tool calls follow the same shape:

mcporter --config "$CONFIG" call ephemeris.get_moon_phase --args '{"datetime":"2026-05-10T12:00:00Z"}'

The moon-phase response includes the next major phase as both an ISO timestamp and a compact relative string:

{
  "phase_name": "Last Quarter",
  "next_major_phase": {
    "phase_name": "New Moon",
    "at_utc": "2026-05-16T20:01:04Z",
    "in_text": "6d 8h 1m"
  }
}

mcporter --config "$CONFIG" call ephemeris.get_lunar_state --args '{"datetime":"2026-05-10T12:00:00Z","lat":52.52,"lon":13.405}'

mcporter --config "$CONFIG" call ephemeris.get_planetary_positions --args '{"datetime":"2026-05-10T12:00:00Z","lat":52.52,"lon":13.405}'

The server is exposed on the LAN at 192.168.0.200:7015 and mounts MCP at /mcp/sse.

Astro-client contract

• get_sky_state is the preferred raw snapshot for downstream chart engines.
• It contains planetary positions, lunar state, sidereal time, and solar events.
• When house_system is provided, it also includes house cusps and angles.
• 22 house systems: P=Placidus, K=Koch, E=Equal, W=Whole Sign, A=Alcabitius, C=Campanus, M=Morinus, R=Porphyry, T=Polich/Page, U=Krusinski-Pisa, V=Vehlow Equal, X=Meridian, Y=Horizontal, H=Azimuthal, O=Equal/MC, F=Carter poli-eq, D=Equal (15° Aries), G=Gauquelin sectors, I=Sunshine, J=Sunshine alt, L=Pullen SD, N=Equal/1, Q=Pullen SR, S=Sripati, Z=APC houses.

Data files

• Swiss Ephemeris data lives in ./data/ephe/ and is bundled into the Docker image.
• Chiron requires seas_18.se1 (and related seas_*.se1 files) — all included.
• The time-segmented files seas_00.se1 through seas_168.se1 cover Chiron from ~675 CE to ~4650 CE.
• The files sepl_*.se1 and semo_*.se1 are needed for far-future dates (beyond 3000 CE).
• Runtime cache (ephemeris.sqlite3) lives in ./data/cache/ and is NOT bundled — it's volume-mounted at runtime.
• All .se1 files are from the Swiss Ephemeris distribution (based on JPL DE441), available at https://github.com/aloistr/swisseph/tree/master/ephe

Docker

• Build and run the service with docker compose up --build.
• data/ephe/ is COPY'd into the image (self-contained, no volume mount needed).
• data/cache/ is volume-mounted for persistent runtime cache.
• The container listens on port 7015 and serves MCP at /mcp/sse.

Working notes

• Keep the server deterministic and easy to reason about.
• Prefer structured outputs over free-form text.
• Keep the repo docs and wiki reference aligned when the scope changes.
• Keep future ideas in the plan even if they are not in v0.2 yet.