Home Explore Help
Sign In
lucky
/
ephemeris-mcp
1
0
Fork 0
Files Issues 0 Pull Requests 0 Wiki
Tree: fc04e6af25
Branches Tags
ephemeris-mcp
/
README.md

README.md 3.9 KB
History Raw

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:

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.