astral-mcp

Purpose

Astral MCP is an astrology calculation MCP server for AI agents, turning birth data into complete, precision-audited astrological readings. It is positioned as a local-first, stateless calculation tool that stores no data and holds no credentials; apart from optional geocoding, all tools can run fully offline. The project was built by David Mosiah, with the astrology engine ported from the Alkhemia app, under the MIT license.

Main Capabilities

The server provides the following tools:

• astral_compute_natal_chart: complete natal chart, with a precision audit by default.
• astral_current_transits: current and upcoming transits, with moon phase included.
• astral_synastry: compares two charts (harmony/chemistry/communication/growth).
• astral_moon_phase: moon phase, sign, and illumination for any date.
• astral_search_birthplace: geocodes a place into latitude/longitude/timezone.
• astral_demo: a complete example chart requiring no input.
• astral_capabilities: what the server does and does not support.
• astral_data_inventory: data domains and recommended first call.
• astral_agent_manifest: installation and usage rules.
• astral_connection_status: health check via an example chart and dual-engine audit.

Every natal chart comes with a precision audit: the primary engine (circular-natal-horoscope-js) calculates the chart, and the verification engine (astronomy-engine) independently re-derives each planet's ecliptic longitude. It is judged verified only when all planets agree within tolerance and fall in the same sign. In the built-in precision suite covering 1945–2010 across six time zones, the maximum cross-engine divergence is below 0.01 degrees.

How to Use

Zero-configuration installation: configure npx -y astral-mcp in an MCP client (Claude Desktop, Cursor, Hermes, etc.) to call it immediately, with no API key, OAuth, or account required. It can also be run directly. It uses stdio transport by default; optional Streamable HTTP (v2 stateless) is limited to loopback, with no session ID and JSON responses. Environment variables: ASTRAL_MCP_HOST, ASTRAL_MCP_PORT, ASTRAL_MCP_TRANSPORT=http.

Privacy modes: the three chart tools (natal chart, transits, synastry) accept a privacy_mode parameter to control payload detail: full (default, including a precision audit for each planet), structured (the same structure with redundant/derivable fields removed), summary (only high-signal essentials, such as luminaries plus Ascendant, chart signature, major aspects). A complete Greenwich natal chart payload is about 6.9 KB, while summary is about 1.2 KB (about an 80% reduction), helping agents save tokens.

Use Cases

Suitable for scenarios that need trustworthy, instant astrological calculations for AI agents, such as: querying a natal chart, checking this week's major transits, performing synastry compatibility analysis, or querying the moon phase. Agents can first call astral_search_birthplace to resolve the birthplace, then call astral_compute_natal_chart.

Limitations and Notes

• Birth time is optional, but if omitted it defaults to noon: planetary signs remain accurate, but the Ascendant and houses are unreliable.
• The birthplace timezone should be passed in, not the caller's timezone; astral_search_birthplace returns the timezone.
• The only optional network call is astral_search_birthplace (OpenStreetMap), which sends only the place-name string passed in.
• The project states that it stores no data and holds no secrets.
• The calculation core is in src/engine/, ported from Alkhemia, and must remain free of framework dependencies; development rules and the test gate (npm test) are in AGENTS.md.
• The security policy is detailed in SECURITY.md, and the license is detailed in LICENSE.
• For more explanation of protocol modes, the separation of deterministic chart calculation from model interpretation, recommended agent workflows, and precision/privacy boundaries, see the related documentation (What Is an Astrology MCP Server?, etc.).loopback, no session ID, JSON responses. Environment variables: ASTRAL_MCP_HOST, ASTRAL_MCP_PORT, ASTRAL_MCP_TRANSPORT=http.

Privacy modes: the three chart tools (natal chart, transits, synastry) accept a privacy_mode parameter to control payload detail: full (default, including a precision audit for each planet), structured (the same structure with redundant/derivable fields removed), summary (only high-signal essentials, such as luminaries plus Ascendant, chart signature, major aspects). A complete Greenwich natal chart payload is about 6.9 KB, while summary is about 1.2 KB (about an 80% reduction), helping agents save tokens.

Use Cases

Suitable for scenarios that need trustworthy, instant astrological calculations for AI agents, such as: querying a natal chart, checking this week's major transits, performing synastry compatibility analysis, or querying the moon phase. Agents can first call astral_search_birthplace to resolve the birthplace, then call astral_compute_natal_chart.

Limitations and Notes

• Birth time is optional, but if omitted it defaults to noon: planetary signs remain accurate, but the Ascendant and houses are unreliable.
• The birthplace timezone should be passed in, not the caller's timezone; astral_search_birthplace returns the timezone.
• The only optional network call is astral_search_birthplace (OpenStreetMap), which sends only the place-name string passed in.
• The project states that it stores no data and holds no secrets.
• The calculation core is in src/engine/, ported from Alkhemia, and must remain free of framework dependencies; development rules and the test gate (npm test) are in AGENTS.md.
• The security policy is detailed in SECURITY.md, and the license is detailed in LICENSE.
• For more explanation of protocol modes, the separation of deterministic chart calculation from model interpretation, recommended agent workflows, and precision/privacy boundaries, see the related documentation (What Is an Astrology MCP Server?, etc.).