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.

Version: 0.8.0

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

Configuration (.env)

Variable	Default	Description
ASTRO_HOST	0.0.0.0	Bind address
ASTRO_PORT	7016	Listen port
ASTRO_DATA_DIR	./data	SQLite DB directory
ASTRO_LOG_DIR	./logs	Log file 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 24h time format in forms (false = 12h with AM/PM)

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)
calculate_transit_chart	Transit chart with natal-to-transit aspects
calculate_synastry_chart	Relationship chart for two people
calculate_composite_chart	Composite chart via midpoint method
get_transit_preview	Daily transit-to-natal aspect snapshot with significance scoring
person_manage	CRUD for persons database
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

Schema

CREATE TABLE persons (
    id              TEXT PRIMARY KEY,
    name            TEXT NOT NULL,
    nickname        TEXT UNIQUE,
    birth_datetime  TEXT NOT NULL,
    latitude        REAL NOT NULL,
    longitude       REAL NOT NULL,
    elevation       REAL DEFAULT 0.0,
    birthplace      TEXT,
    alive           BOOLEAN DEFAULT 1,
    private         BOOLEAN DEFAULT 0,
    gender          TEXT,
    description     TEXT,
    notes           TEXT,
    timezone        TEXT,
    birth_time_known BOOLEAN DEFAULT 1,
    created_at      TEXT NOT NULL,
    updated_at      TEXT
);

All columns added via non-destructive ALTER TABLE migrations.

person_manage tool

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

Features

• Person list with name, nickname, birth date, location, gender, status badges
• Add/Edit form with:
  • Native date picker + time input (12h or 24h based on DASHBOARD_24H_TIME)
  • Timezone select with 50+ IANA zones grouped by region
  • Live UTC offset display (e.g. "UTC+01:00 (CEST)")
  • GeoNames autocomplete for birthplace (requires GEONAMES_USERNAME) — auto-fills lat/lon/elevation/timezone
• Detail view with all fields, notes, metadata
• Export individual persons or all persons as JSON
• Import persons from JSON file (single object or array)
• Delete with confirmation dialog

Import/Export Format

[
  {
    "name": "John Doe",
    "nickname": "john",
    "birth_datetime": "1990-05-15T08:30:00+02:00",
    "birthplace": "Vienna, Austria",
    "latitude": 48.2082,
    "longitude": 16.3738,
    "elevation": 171,
    "alive": true,
    "private": false,
    "gender": "male",
    "description": "A sample person",
    "notes": "Some notes here",
    "timezone": "Europe/Vienna",
    "birth_time_known": true
  }
]

Required fields: name, birth_datetime, latitude, longitude. All others are optional.