Skip to main content
Glama
Astral MCP

Astral MCP

⚡ Zero-setup install. Wire it into Claude Desktop / Cursor / Hermes and call it immediately — no API key, no OAuth, no account: npx -y astral-mcp

A local-first MCP server that turns birth data into a full, precision-audited astrological reading for AI agents. Stateless and computational — nothing is stored, no credentials exist, and every tool but optional geocoding runs fully offline.

Astral MCP is Delx's focused astrology product. See the Delx platform map for its boundary with the separate Protocol, Security, Wellness and Commerce properties.

Built by David Mosiah. The astrology engine is ported from the Alkhemia app.

New to the protocol pattern? Read What Is an Astrology MCP Server? for the separation between deterministic chart computation and model interpretation, the recommended agent workflow, and the precision/privacy boundaries.

Ready to calculate one? Follow How to Generate a Natal Chart with MCP for the exact birthplace, timezone, unknown birth-time, payload and precision-audit workflow.

Handling sensitive inputs? Read How to Protect Birth Data in Astrology Agent Workflows for payload minimization, local computation, the optional OpenStreetMap boundary and the limits of privacy_mode=summary.

Why this exists

Most astrology libraries are fragile single-engine wrappers, and most "astrology APIs" want a key and a subscription. Agents need something they can trust and call instantly. Astral MCP does two things differently:

  1. It just works. npx -y astral-mcp and you're calling charts — no OAuth, no account, no birthplace database to install.

  2. It checks itself. Every natal chart is computed with one ephemeris and then independently re-derived, planet by planet, with a second one. If they disagree beyond a tight tolerance, the chart is flagged review instead of silently returning a wrong placement.

Related MCP server: Astro MCP Server

Setup in 60 seconds

Add it to your MCP client (Claude Desktop, Cursor, Hermes, …):

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

That's the whole setup. There is nothing to authenticate.

Run it directly if you want:

npx -y astral-mcp                      # stdio (default)
ASTRAL_MCP_TRANSPORT=http npx -y astral-mcp   # streamable HTTP on 127.0.0.1:3000

See it before you connect

Call astral_demo for a fully-worked example chart (Greenwich, noon, Y2K) including its precision audit — no input, no network, no auth. It shows you the exact payload shape before you send real birth data.

Try it with your agent

"What's my natal chart? I was born 23 Feb 1989, 14:30, in Fortaleza, Brazil."

The agent calls astral_search_birthplace to resolve Fortaleza → lat/lon/timezone, then astral_compute_natal_chart.

"Any big transits hitting my chart this week?" → astral_current_transits "How compatible are we?" (two birth datas) → astral_synastry "What phase is the moon in today?" → astral_moon_phase

Precision

Astral MCP ships every natal chart with a precision audit. The primary engine (circular-natal-horoscope-js) computes the chart; the verifier (astronomy-engine) re-derives each planet's ecliptic longitude independently. A chart is verified only when every planet agrees within tolerance and lands in the same sign.

Across a built-in accuracy suite of charts spanning 1945–2010 and six timezones, the worst cross-engine disagreement is under 0.01°. Run it yourself:

npm run test:accuracy

Data availability

Capability

Supported

Planets (Sun…Pluto), Ascendant, MC/IC

✅

Houses (placidus, koch, campanus, regiomontanus, topocentric, equal-house, whole-sign)

✅

Major aspects with orb, strength, applying/separating

✅

Chart signature (dominant element/modality, pattern, stelliums, angular planets)

✅

Retrogrades · timezone/DST handling

✅

Transits (current + upcoming) · moon phase

✅

Synastry (two-chart comparison, scored)

✅

Tropical & sidereal zodiac

✅

Lunar nodes, Chiron, asteroids, fixed stars

⏳ planned

Minor aspects

⏳ planned

Interpretation text

❌ by design — astral-mcp returns structured data; your model writes the reading

Tools

  • astral_compute_natal_chart — full natal chart, precision-audited by default

  • astral_current_transits — current + upcoming transits to a chart, with moon phase

  • astral_synastry — compare two charts (harmony / chemistry / communication / growth)

  • astral_moon_phase — moon phase, sign and illumination for any date

  • astral_search_birthplace — geocode a place to latitude / longitude / timezone

  • astral_demo — worked example chart, no input needed

  • astral_capabilities — what this server supports and what it doesn't

  • astral_data_inventory — data domains and recommended first calls

  • astral_agent_manifest — install + usage rules for agents

  • astral_connection_status — health check via a sample chart + dual-engine audit

The three chart tools (astral_compute_natal_chart, astral_current_transits, astral_synastry) take a privacy_mode parameter — a payload-verbosity axis separate from response_format:

  • full (default) — the complete payload, including the per-planet precision audit

  • structured — same structure, redundant/derivable fields dropped

  • summary — only the high-signal essentials (luminaries + Ascendant, chart signature, top aspects)

A full Greenwich natal payload is ~6.9 KB; summary is ~1.2 KB (~80% smaller), so an agent that only needs a quick read can ask for less and spend fewer tokens.

Notes for accurate readings

  • Pass the birthplace timezone, not the caller's. astral_search_birthplace returns it.

  • birth_time is optional. Without it, noon is assumed: planet signs stay accurate, but the Ascendant and houses are unreliable.

Privacy & Security

Astral MCP stores nothing and holds no secrets. The only optional network call is astral_search_birthplace (OpenStreetMap), which sends just the place-name string you pass. See SECURITY.md.

Contributing

The computation core in src/engine/ is ported from Alkhemia — keep it framework-free. See AGENTS.md for the development rules and the test gate (npm test).

License

MIT — see LICENSE.

HTTP (v2 stateless)

Default is stdio. Optional Streamable HTTP — no session id, JSON responses, loopback only:

npx -y astral-mcp --http
# GET  http://127.0.0.1:3000/health
# POST http://127.0.0.1:3000/mcp   (sessionless)

Env: ASTRAL_MCP_HOST, ASTRAL_MCP_PORT, ASTRAL_MCP_TRANSPORT=http.

Skill or MCP

npx -y astral-mcp call astral_connection_status --json '{}'

Available Tools

10 tools
astral_agent_manifestAstral Agent ManifestA
Read-onlyIdempotent

Agent-oriented setup and usage guide: install command, recommended first calls, the full tool list, agent rules (resolve birthplace first, pass birthplace timezone, birth_time caveats) and troubleshooting. Call this to learn how to drive astral-mcp correctly.

Inputs: response_format. Returns: links, package, project, mcp_name, +5 more

astral_capabilitiesAstral CapabilitiesA
Read-onlyIdempotent

Explain what astral-mcp can compute: supported house systems, zodiacs, bodies, aspects and features, the dual-engine precision model, what is NOT included (nodes, Chiron, interpretations), and the recommended agent workflow. Read this first to plan a sequence of calls.

Inputs: response_format. Returns: links, creator, engines, project, +4 more

astral_compute_natal_chartCompute Natal ChartA
Read-onlyIdempotent

Compute a full natal (birth) chart from birth data: planet signs/degrees/houses, retrogrades, major aspects with orb and strength, the Ascendant/MC, and a derived signature (dominant element/modality, chart pattern, stelliums, angular planets). By default the chart is precision-audited by a second independent ephemeris. This is the primary tool. If you only have a city name, call astral_search_birthplace first to get latitude/longitude/timezone. Use privacy_mode to control payload size (a full chart is large): 'full' (default) returns everything; 'structured' drops redundant fields; 'summary' returns only the luminaries, Ascendant, chart signature and top aspects to save tokens.

Inputs: latitude (required), timezone (required), longitude (required), birth_date (required), +6 more. Returns: meta, houses, aspects, context, +2 more

astral_connection_statusAstral Connection StatusA
Read-onlyIdempotent

Health check. The server is stateless and local, so this verifies the Node version and proves both bundled ephemerides load and agree by computing a sample chart and running the dual-engine precision audit. Call this to confirm the install is working before computing real charts.

Inputs: response_format. Returns: ok, node, notes, ready, +3 more

astral_current_transitsCurrent TransitsA
Read-onlyIdempotent

Read the current (or a chosen date's) planetary transits against a natal chart. Returns the active transit aspects to the natal planets and angles, upcoming activation windows over the next days, and the current moon phase. Supply the same birth data you would for a natal chart; pass on_date/on_time to read a specific moment. Useful for 'what's happening for me astrologically' questions. Set privacy_mode=summary for just the moon phase and top transit aspects (omitting the full current-sky planet map), 'structured' for a leaner payload, or 'full' (default) for everything.

Inputs: latitude (required), timezone (required), longitude (required), birth_date (required), +8 more. Returns: moon, note, abridged, timezone, +7 more

astral_data_inventoryAstral Data InventoryA
Read-onlyIdempotent

Inventory the data domains this server exposes (natal, transits, relationship, geocoding), which tools serve each, and the recommended first calls. Does not compute anything or take any input beyond response_format.

Inputs: response_format. Returns: kind, notes, mcp_name, categories, +3 more

astral_demoAstral DemoA
Read-onlyIdempotent

Return a fully-worked example natal chart (Greenwich, noon, 2000-01-01) including a precision audit, so you can see the exact payload shape before sending real birth data. The returned 'input' is a ready-to-send argument object for astral_compute_natal_chart — copy it and swap in real birth data; 'chart' is exactly what that call returns at the default privacy_mode=full. No input, no network, no auth.

Inputs: response_format. Returns: kind, note, chart, input

astral_moon_phaseMoon PhaseA
Read-onlyIdempotent

Get the moon phase (new, waxing, full, waning, etc.), the moon's sign, illumination percentage and sun–moon angle for now or a chosen local date/time. Location-independent — no birth data needed. Good for ritual timing, journaling prompts, or 'what phase is the moon in' questions.

Inputs: on_date, on_time, timezone, response_format. Returns: angle, phase, moonSign, timezone, +2 more

astral_search_birthplaceSearch BirthplaceA
Read-onlyIdempotent

Geocode a city or place name into latitude, longitude and IANA timezone using OpenStreetMap (free, no key). Call this FIRST whenever you only have a place name, then pass the chosen match's coordinates and timezone to the chart tools. Returns several matches; pick the one whose displayName matches the intended birthplace.

Inputs: query (required), language, response_format. Returns: count, query, results

astral_synastrySynastry (Two-Chart Comparison)A
Read-onlyIdempotent

Compare two birth charts (synastry). Returns the inter-chart aspects between the two people's planets and angles, plus scored dimensions (harmony, chemistry, communication, growth) and an overall 0–100 score with a tone. Provide both people's birth data under 'person' and 'partner'. Resolve any city names with astral_search_birthplace first. Set privacy_mode=summary for just the score, tone, dimensions and strongest aspects; 'full' (default) returns the complete aspect list.

Inputs: person (required), partner (required), zodiac, house_system, +2 more. Returns: note, tone, score, aspects, +3 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 10 tools

    Disambiguation3/5

    The four computational tools (natal chart, transits, synastry, moon phase) are clearly distinct, but the three informational tools (capabilities, data inventory, agent manifest) overlap in purpose and could confuse an agent choosing which to call. The remaining support tools (birthplace search, demo, connection status) are well-separated.

    Naming Consistency4/5

    All tools share the consistent astral_ prefix and use snake_case, giving the set a unified look. However, naming style is mixed: some use verb_noun (compute_natal_chart, search_birthplace) while most are plain nouns (synastry, moon_phase, demo, capabilities), which is a minor inconsistency.

    Tool Count4/5

    Ten tools is a reasonable count for an astrology server, and each core capability has a dedicated tool. However, five of the ten are meta/informational tools (capabilities, inventory, manifest, demo, status), which feels slightly heavy relative to the five functional tools, though still within an acceptable range.

    Completeness4/5

    The server covers the main astrological workflows: natal charts, transits, synastry, moon phase, and geocoding prerequisites. Missing advanced features like progressions or solar returns are acknowledged omissions rather than dead ends, so agents can complete typical tasks without gaps.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      B
      maintenance
      Comprehensive astrology MCP exposing every endpoint of the AstroWay Calculation API — natal charts, synastry, transits, Vedic dashas, Tarot, Numerology, Human Design. Sub-arcsecond Swiss Ephemeris precision, 10 000 free credits per month.
      500
      292 npm
      4
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Multi-tradition astrology engine that computes real birth charts, transits, and synastry for AI agents via MCP tools.
      18
      -
    • A
      license
      A
      quality
      C
      maintenance
      Astrology MCP server that computes natal charts, transits, synastry, progressions, returns, eclipses, retrogrades, and moon phases from a real ephemeris, enabling AI agents to provide accurate astrological calculations without hallucination.
      12
      75 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      High-precision astrology tools for LLM agents, including natal charts, transits, progressions, synastry, and more, backed by Swiss Ephemeris.
      1
      MIT