Astro MCP

A Vedic (sidereal) astrology engine exposed as an MCP server, built so an LLM such as Claude can answer questions like "what dasha am I running?" or "how is Saturn transiting for me?". Answers come from real calculations, returned in a compact format that uses few tokens.

• Calculations are done with PyJHora and the Swiss Ephemeris, behind a small backend-agnostic API (engine.py).

• Validated against JHora desktop:

  • Planets and nodes agree within 0.03″ and the Lagna within 0.1″, on a public chart (1926, Los Angeles) and a private reference chart.

  • Vimshottari boundaries agree within ~40 s on the private chart.

• Defaults: True Chitra ayanamsa (what JHora calls "Lahiri"), mean nodes, whole-sign houses, and solar-return dasha years.

MCP tools

The full tool schema set is about 600 tokens. Typical responses are 35–200 tokens, for example:

D1 TRUE_LAHIRI mean-node whole-sign
As Cn 20:27 Ashlesha2 H1
Mo Cp 26:17 Dhanishta1 H7
Sa Li 28:37 Vishakha3 H4 R

• Bodies: As Su Mo Ma Me Ju Ve Sa Ra Ke. Signs: Ar..Pi.

• Ashlesha2 means nakshatra plus pada.

• H is the whole-sign house counted from the Lagna; M is the house counted from the Moon.

• R means retrograde. R→D <date> is when it turns direct.

Related MCP server: kundali-mcp

Design notes

• Nothing personal is stored. Charts live only in an in-memory LRU cache.

  • A chart_id is the birth data plus settings, encrypted with AES-SIV under a persistent server key. After a restart the server rebuilds the chart from the id alone.

  • Without the key an id reveals nothing, and it can't be checked against guessed birth data.

• No guessing:

  • An ambiguous place name ("Springfield", "Nizamabad, India") returns the list of candidates, and the model is told to ask the user.

  • A time that falls in a DST gap or overlap returns both possible UTC offsets, and the model is told to ask the user.

  • The model is instructed to pass the place exactly as the user said it.

• Historical timezones come from tzdata and timezonefinder, which covers war time, rule changes and local mean time before standard time was adopted.

• Geocoding is offline (GeoNames cities500). A place name resolves to the city center, and the output says so.

Setup

Requires Python 3.12.

python -m venv .venv
.venv/Scripts/python -m pip install -r requirements.txt      # Windows; use .venv/bin/python elsewhere
.venv/Scripts/python scripts/fetch_ephe.py                   # Swiss Ephemeris files -> data/ephe/ (~100 MB)
.venv/Scripts/python scripts/fetch_geonames.py               # GeoNames -> data/geonames/ + SQLite index (~140 MB)
.venv/Scripts/python -m pytest tests                         # tests

Chart-id key: in production, set ASTRO_ENGINE_CHART_KEY to a hex string of at least 32 bytes. If it isn't set, a key is generated once in .secrets/chart_id.key, which is gitignored. Changing the key invalidates every issued chart_id.

Claude Desktop (claude_desktop_config.json; the Microsoft Store build keeps it under %LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\):

{
  "mcpServers": {
    "astro-engine": {
      "command": "C:\\path\\to\\astro-engine\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\astro-engine\\mcp_server.py"]
    }
  }
}

Layout

tests/private/ and scratch/ are gitignored. They hold owner-specific reference data.

License and attribution

• This project: GNU AGPL-3.0, as required by its dependencies.

• PyJHora: AGPL-3.0.

• Swiss Ephemeris: AGPL-3.0, or a commercial license from Astrodienst.

• Geographic data: © GeoNames, CC BY 4.0.