astro-mcp

astro-mcp v0.2.0

Version 0.2.0.

Astro-MCP is an MCP server for astrological chart calculations and database-backed chart artifact delivery. It consumes ephemeris-mcp:get_sky_state through MCP-over-SSE and exposes structured calculation tools, MCP resources for rendered charts, and HTTP chart URLs for human-facing clients.

v0.2.0 delivery surface

Chart rendering is implemented internally and is not exposed as MCP tools. The render_* MCP tools have been removed.

Rendered natal charts for persons in the database are available as the MCP resource template:

astro://charts/natal/{person_id}

The resource returns the default SVG artifact. The human-facing HTTP equivalent accepts the existing renderer format suffixes:

/charts/natal/{person_id}.{format}

Examples:

astro://charts/natal/einstein
/charts/natal/einstein.svg
/charts/natal/einstein.png

The MCP resource and HTTP route use the existing natal calculation and chart-rendering implementation. They do not add rendering behavior or alter the chart drawing code.

Only natal chart artifact delivery is implemented in v0.2.0. Other chart resource families are not exposed yet.

Quick start

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
./run.sh

The server listens on port 7016 by default. The port is configurable with ASTRO_PORT.

Docker

docker compose up --build

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

Configuration

Variable	Default	Description
ASTRO_HOST	0.0.0.0	Bind address
ASTRO_PORT	7016	Listen port
ASTRO_DATA_DIR	./data	SQLite database directory
ASTRO_LOG_DIR	./logs	Log directory
EPHEMERIS_MCP_URL	http://192.168.0.200:7015/mcp/sse	Ephemeris MCP endpoint
GEONAMES_USERNAME	empty	GeoNames username for birthplace autocomplete
DASHBOARD_24H_TIME	true	Use 24-hour time in dashboard forms

MCP endpoint

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

Calculation tools

The calculation surface remains structured-data oriented:

Tool	Purpose
get_planetary_positions	Planetary positions with signs, degrees, and retrograde flags
calculate_natal_chart	Natal chart from direct birth data
calculate_transit_chart	Transit-to-natal chart calculation
calculate_synastry_chart	Two-person relationship chart calculation
calculate_composite_chart	Composite chart calculation
calculate_davison_chart	Davison chart calculation
get_transit_preview	Transit-to-natal snapshots over a date range
get_composite_transit_preview	Composite transit preview
get_davison_transit_preview	Davison transit preview
get_karmic_relationship_summary	Structured relationship summary
person_manage	Person database management
list_house_systems	Supported house systems

Database-backed calculation variants include the relevant _by_id tools and accept a person ID or nickname.

Person database datetime convention

The database stores birth_datetime as naive local time and timezone as an IANA timezone name. For example:

birth_datetime = 1953-03-23T21:05:00
timezone = America/Chicago

UTC conversion happens in _get_person_birth_data(). Do not store UTC or offset-aware values in the database birth_datetime column.

Dashboard

The person-management dashboard is available at:

http://localhost:7016/dashboard

It supports listing, adding, editing, importing, exporting, and deleting persons. Chart artifact delivery is available independently through the /charts/natal/{person_id}.{format} HTTP route.

Verification

Run the test suite with:

pytest

The v0.2.0 contract includes removal of all render_* MCP tools, registration of astro://charts/natal/{person_id}, and the human-facing natal chart HTTP route.