ephemeris-mcp

Ephemeris MCP

Ephemeris MCP is a standalone celestial computation engine exposed through MCP. v0.1 ships the core sky-state slice: planetary positions, solar events, lunar state, moon phase, sidereal time, constellation lookup, discovery, and a raw sky-state snapshot for downstream chart engines. Satellite tooling remains planned for later slices.

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

What it is

• A shared sky-state service for time- and location-dependent calculations
• A source of planetary positions, solar events, lunar state, sidereal time, and constellation lookup
• A convenience moon-phase tool for quick manual checks
• A raw sky-state snapshot tool for downstream chart engines
• A utility layer for downstream consumers that want raw sky data

What it is not

• Not an interpretation engine
• Not a charting service
• Not a consumer-facing astrology app
• Not a finished satellite tracking stack in v0.1

Project direction

The implementation is intentionally split between:

• objective ephemeris computation
• 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
• .env.example - optional runtime environment template
• tests.sh - test runner
• data/ - local ephemeris/cache data
• logs/ - runtime logs
• mcporter - preferred manual client for smoke tests

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.249: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.
• Houses, Placidus, and zodiac-sign placement stay outside this repo.

Data files

• Chiron requires the Swiss Ephemeris main asteroid file seas_18.se1 in ./data/.
• If that file is missing, get_planetary_positions will still return the other bodies, but Chiron will error until the file is present.

Docker

• Build and run the service with docker compose up --build.
• The compose file mounts ./data and ./logs into the container.
• Keep seas_18.se1 in ./data before starting the container if you want Chiron in the response set.
• 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.1 yet.