Astral MCP

What the davidmosiah/astral-mcp MCP server does

The davidmosiah/astral-mcp MCP server exposes astrology calculations through the Model Context Protocol. It accepts birth information and related dates, then returns structured data for natal charts, current and upcoming transits, synastry, and lunar phases. A birthplace lookup tool can resolve a place name to latitude, longitude, and timezone before chart calculation.

Natal charts include planets from the Sun through Pluto, angles such as the Ascendant and MC/IC, supported house systems, major aspects, chart signatures, retrogrades, and timezone or daylight-saving handling. The listed zodiac options include tropical and sidereal modes. Transits include a Moon phase, while synastry compares two charts across harmony, chemistry, communication, and growth dimensions.

Interpretation text is intentionally outside the server's scope. The MCP tools return structured astrology data for the connected model or application to interpret.

How it works

The server is local-first and stateless. Natal calculations use a primary ephemeris and a separate verification engine to re-derive planetary positions. A chart is marked as verified only when the two calculations agree within the configured tolerance and place each planet in the same sign; otherwise, it is flagged for review.

The three main chart tools support a privacy_mode setting. full returns the complete payload and precision audit, structured removes redundant or derivable fields, and summary limits the response to high-signal items such as the luminaries, Ascendant, chart signature, and top aspects. This controls response detail rather than changing the calculation.

The server assumes noon when birth_time is omitted. Planet signs remain useful in that case, but the Ascendant and houses are unreliable. For location lookup, the optional astral_search_birthplace call sends the supplied place name to OpenStreetMap. The server otherwise performs its calculations offline and stores no inputs.

Setup and configuration

Install the davidmosiah/astral-mcp MCP server with the following stdio configuration:

{
  "mcpServers": {
    "astral": {
      "command": "npx",
      "args": ["-y", "astral-mcp"]
    }
  }
}

No credentials, API key, OAuth flow, or account are required. The default transport is stdio. The HTTP examples bind to loopback and expose a health endpoint plus a sessionless MCP endpoint.

Tools and capabilities

• astral_compute_natal_chart: Calculates a natal chart with a precision audit by default.
• astral_current_transits: Returns current and upcoming transits to a chart, including the Moon phase.
• astral_synastry: Compares two charts with scored relationship dimensions.
• astral_moon_phase: Reports the Moon phase, sign, and illumination for a date.
• astral_search_birthplace: Looks up a place's coordinates and timezone.
• astral_demo: Returns a worked example chart without input or network access.
• astral_capabilities, astral_data_inventory, and astral_agent_manifest: Describe supported data, recommended calls, and usage rules.
• astral_connection_status: Runs a sample-chart health check with a dual-engine audit.

Limitations and notes

The server does not provide interpretation text. Lunar nodes, Chiron, asteroids, fixed stars, and minor aspects are listed as planned rather than supported. Birthplace lookup is the only documented operation that may use the network. When birth time is unknown, avoid treating houses or the Ascendant as reliable. The project is released under the MIT license.