astro-mcp

astro-mcp

MCP server for astrological chart calculations. Consumes ephemeris-mcp:get_sky_state via MCP-over-SSE client and exposes calculated astrological data (natal charts, transits, synastry, transit previews) as structured JSON tools.

Quick Start

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
./run.sh

Server listens on port 7016 (configurable via ASTRO_PORT).

Docker

docker compose up --build

Health check: GET http://localhost:7016/health

MCP Endpoint

SSE transport at http://localhost:7016/mcp/sse

Tools

Core tools (raw birth data)

Tool	Description
get_planetary_positions	Planetary positions with zodiac signs, degrees, retrograde flags
calculate_natal_chart	Complete natal chart (planets, houses, aspects, angles). Params: birth_datetime, latitude, longitude
calculate_transit_chart	Transit chart with natal-to-transit aspects. Params: birth_datetime, transit_datetime, latitude, longitude, transit_latitude, transit_longitude
calculate_synastry_chart	Relationship chart for two people. Params: person1_datetime/lat/lon, person2_datetime/lat/lon
calculate_composite_chart	Composite chart via midpoint method. Params: same as synastry
get_transit_preview	Daily transit-to-natal aspect snapshot. Params: birth_datetime, latitude, longitude, start_date, end_date
person_manage	CRUD for persons database (name, nickname, birthplace, birth_datetime, lat/lon, elevation)
list_house_systems	List supported house systems

_byId tools (database-backed)

Each core chart tool has a _byId variant that accepts a person_id (from the persons database) instead of raw birth data. All other optional parameters override the defaults.

Tool	Description
calculate_natal_chart_by_id	Natal chart by person_id
calculate_transit_chart_by_id	Transit chart by person_id + transit_datetime
calculate_synastry_chart_by_id	Synastry chart for person1_id + person2_id
calculate_composite_chart_by_id	Composite chart for person1_id + person2_id
get_transit_preview_by_id	Transit preview by person_id + date range

Person database

person_manage supports actions: add, get (by id or nickname), list, update, delete.

Example workflow:

person_manage(action="add", name="Me", birth_datetime="1965-07-02T00:05:00+02:00",
              birthplace="Graz, Austria", latitude=47.076668, longitude=15.421371)
=> {"person": {"id": "abc12345", ...}}

# Then use the _byId tools:
calculate_natal_chart_by_id(person_id="abc12345")
calculate_transit_chart_by_id(person_id="abc12345", transit_datetime="2026-06-02T12:00:00")

Dashboard

Person management dashboard at http://localhost:7016/dashboard