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, health, and root. 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 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
• 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-16T03:18:00Z",
    "in_text": "5d 15h 18m"
  }
}

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.

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.