Astral MCP
Astral MCP is a local, stateless MCP server that provides precision-audited astrological computations for AI agents — no API keys or accounts required.
Core Capabilities
Natal Charts: Generate full birth charts with planet positions, houses, aspects, retrogrades, and chart signature. Support for 7 house systems (Placidus, Whole Sign, etc.), tropical & sidereal zodiacs, dual-engine precision audit (<0.01°), and payload privacy modes (full/structured/summary). Output in markdown or JSON.
Current & Future Transits: Show planetary transits to a natal chart, including upcoming activation windows and moon phase. Specify any date/time.
Synastry: Compare two charts for compatibility, including inter-chart aspects and scored dimensions (harmony, chemistry, communication, growth) with a 0–100 overall score.
Moon Phase: Get the moon's phase, sign, illumination percentage, and sun–moon angle for any date/time — no birth data needed.
Geocoding: Convert place names to latitude, longitude, and IANA timezone via OpenStreetMap (no API key; optional, otherwise fully offline).
Utility Tools
Demo Chart: Retrieve a sample natal chart with precision audit to preview the payload structure.
Capabilities & Data Inventory: Query supported features, house systems, zodiacs, bodies, aspects, and data domains.
Agent Manifest: Get setup instructions, tool list, agent rules, and troubleshooting.
Connection Health Check: Verify server operation by testing ephemeris engines with a sample chart.
Key Features
Dual‑Engine Precision: Independent validation by two ephemerides; worst disagreement under 0.01°.
Privacy Modes: “full”, “structured”, or “summary” to control response size (up to ~80% smaller).
Local & Offline: Stateless; stores nothing, requires no credentials. Network only needed for optional geocoding.
Flexible Output: Choose between human‑readable markdown or structured JSON.
Provides geocoding services to convert place names into latitude, longitude, and timezone for astrology calculations.
⚡ 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:
It just works.
npx -y astral-mcpand you're calling charts — no OAuth, no account, no birthplace database to install.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
reviewinstead 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:3000See 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:accuracyData 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 defaultastral_current_transits— current + upcoming transits to a chart, with moon phaseastral_synastry— compare two charts (harmony / chemistry / communication / growth)astral_moon_phase— moon phase, sign and illumination for any dateastral_search_birthplace— geocode a place to latitude / longitude / timezoneastral_demo— worked example chart, no input neededastral_capabilities— what this server supports and what it doesn'tastral_data_inventory— data domains and recommended first callsastral_agent_manifest— install + usage rules for agentsastral_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 auditstructured— same structure, redundant/derivable fields droppedsummary— 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_birthplacereturns it.birth_timeis 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 toolsastral_agent_manifestAstral Agent ManifestARead-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 CapabilitiesARead-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 ChartARead-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 StatusARead-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 TransitsARead-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 InventoryARead-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 DemoARead-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 PhaseARead-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 BirthplaceARead-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)ARead-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
Scored across 10 tools
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.
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.
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.
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
Related MCP Connectors
Official Divine API MCP for Western Astrology: Natal, Synastry, Transit, Composite, Progressions.
Ephemeris-grade natal charts, current transits, zodiac sign profiles. No API key.
34-tool Caelus MCP for validated astrology: charts, transits, Vedic, facts, sky view, synthetic.
Our own engine on NASA JPL data, no third-party APIs: natal, transits, synastry and 40+ techniques.
Related MCP Servers
AlicenseCqualityBmaintenanceComprehensive 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.500292 npm4MIT- FlicenseNot gradedqualityCmaintenanceMulti-tradition astrology engine that computes real birth charts, transits, and synastry for AI agents via MCP tools.18-
- AlicenseAqualityCmaintenanceAstrology 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.1275 npm1MIT
- AlicenseNot gradedqualityBmaintenanceHigh-precision astrology tools for LLM agents, including natal charts, transits, progressions, synastry, and more, backed by Swiss Ephemeris.1MIT