astro-mcp/agent-guides/server-guide.md

Astro-MCP Server Guide

Overview

Astro-MCP is an astrological chart calculation server. It consumes birth data and returns planetary positions, house cusps, angles, and aspects. All computation is delegated to a separate ephemeris-mcp server which runs the Swiss Ephemeris library.

Architecture

User / Agent
    |
    v
astro-mcp (this server)
    |  MCP SSE
    v
ephemeris-mcp (Swiss Ephemeris backend)

• astro-mcp handles: person database, chart interpretation, rendering, timezone conversion, MCP tool interface
• ephemeris-mcp handles: raw astronomical computation (planetary positions, house cusps, sidereal time)

Timezone Rules (CRITICAL)

Single Conversion Point

_get_person_birth_data() is the ONLY function that converts stored birth datetimes to UTC. It reads the naive local time and IANA timezone name from the persons database, combines them, and returns a UTC datetime. All _byId chart tools call this function. No other function performs timezone conversion.

Database Storage Format

• birth_datetime: naive local time, NO offset (e.g. "1965-07-02T00:05:00")
• timezone: IANA timezone name (e.g. "Europe/Vienna", "America/New_York")
• longitude: used as fallback for LMT when timezone is missing

Direct-Call Tools

Tools that accept birth_datetime as a parameter (e.g. calculate_natal_chart, calculate_transit_chart) expect UTC or offset-aware datetimes. The caller is responsible for conversion. Use ISO 8601 format:

• UTC: "1965-07-01T23:05:00Z" or "1965-07-01T23:05:00+00:00"
• Offset-aware: "1965-07-02T00:05:00+01:00"

_byId Tools

Tools that look up persons by ID/nickname (e.g. calculate_natal_chart_by_id) automatically convert to UTC. Just pass the person identifier.

Person Management

Adding a Person

Use person_manage with action: "add". Required fields:

• name: Full name
• birth_datetime: ISO 8601 datetime (any format — will be stored)
• latitude, longitude: Birth coordinates
• tz: IANA timezone name (e.g. "Europe/Vienna")

Optional: nickname, birthplace, elevation, gender, description, notes, birth_time_known.

Important: Timezone Must Be Set

When adding a person, ALWAYS provide the tz field with the correct IANA timezone name. This is essential for accurate chart calculation, especially for:

• Historical dates (before ~1890) where LMT differs from modern timezones
• Locations that observed DST differently in the past
• Any date where the UTC offset is not obvious

Listing and Updating

• person_manage with action: "list" — list all persons
• person_manage with action: "get" — retrieve by ID or nickname
• person_manage with action: "update" — modify fields
• person_manage with action: "delete" — remove person

Tool Categories

Data-Only Tools (return JSON)

Tool	Description
get_sky_state	Raw planetary positions + houses for a datetime/location
calculate_natal_chart	Full natal chart: planets, houses, aspects, angles
calculate_transit_chart	Transit-to-natal aspects
calculate_synastry_chart	Relationship chart for two people
calculate_composite_chart	Composite (midpoint) chart
calculate_davison_chart	Davison (space-time midpoint) chart
get_transit_preview	Daily transit snapshots over a date range
get_karmic_relationship_summary	Karmic analysis for a relationship

_byId Variants (lookup person from DB)

Same as above but with _byId suffix. Accept person_id (or nickname) instead of birth data. Automatically handle timezone conversion.

Rendering Tools (return SVG)

Tool	Description
render_natal_chart	SVG natal chart wheel
render_transit_chart	SVG transit chart
render_synastry_chart	SVG synastry chart
render_composite_chart	SVG composite chart
render_davison_chart	SVG Davison chart

Each has a _byId variant.

Utility Tools

Tool	Description
person_manage	CRUD for persons database
list_house_systems	List supported house systems (Placidus, Koch, etc.)

House Systems

Supported house system codes: P (Placidus), K (Koch), E (Equal), W (Whole Sign), A (Alcabitius), C (Campanus), M (Morinus), R (Porphyry), and more. Use list_house_systems for the full list.

Default is Placidus.

Common Workflows

Natal Chart for a Known Person

1. person_manage(action="add", name="...", birth_datetime="...", latitude=..., longitude=..., tz="...")
2. calculate_natal_chart_by_id(person_id="...", include_overview=true)

Natal Chart for a One-Off Calculation

calculate_natal_chart(
    birth_datetime="1990-05-15T10:30:00+01:00",  # UTC or offset-aware
    latitude=47.07,
    longitude=15.42,
    include_overview=true
)

Transit Chart

calculate_transit_chart_by_id(
    person_id="...",
    transit_datetime="2026-06-07T12:00:00Z"  # UTC
)

Relationship Analysis

calculate_synastry_chart_by_id(
    person1_id="...",
    person2_id="...",
    include_davison_full=true
)

Rendered Chart

render_natal_chart_by_id(
    person_id="...",
    style="modern",
    color_mode="color",
    size=800
)

Resources (fetch with astro:// URI)

URI	Content
astro://guides/natal-astrology	Natal chart interpretation guide
astro://guides/karmic-astrology	Karmic astrology guide
astro://guides/relationship-astrology	Relationship astrology guide
astro://guides/financial-astrology	Financial astrology guide

Error Handling

All tools return {"error": "message"} on failure. Common errors:

• "person not found: ..." — invalid person_id or nickname
• "add requires: name, birth_datetime, latitude, longitude" — missing fields
• "empty_response" — ephemeris server unreachable

Tips

1. Always use _byId tools when working with stored persons — they handle timezone conversion automatically.
2. For direct-call tools, pass UTC datetimes to avoid ambiguity.
3. The include_overview flag adds element/modality/hemisphere balance, stelliums, empty houses, chart ruler, and house rulers.
4. The include_patterns flag adds T-square, Grand Trine, Grand Cross, Yod detection and chart shape classification.
5. The include_karmic flag adds nodal axis, Saturn, Pluto polarity point, Part of Fortune, and 12th house analysis.
6. Use top_n_aspects to limit aspect output to the N tightest by orb.