{ "markdown": "\n

Astral MCP

\n\n
\n \"Astral\n
\n\n

\n Give your AI agent real astrology — natal charts, transits, synastry & moon phases.
\n Computed locally, cross-checked by two independent ephemerides. No API key, no account.\n

\n\n

\n \"npm\n \"npm\n \"License\n \"Built\n

\n\n

\n \"GitHub\n \"Precision\n \"Zero\n

\n\n> ⚡ **Zero-setup install.** Wire it into Claude Desktop / Cursor / Hermes and call it immediately — no API key, no OAuth, no account:\n> `npx -y astral-mcp`\n\n**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.\n\nAstral MCP is Delx's focused astrology product. See the [Delx platform map](https://delx.ai/platform) for its boundary with the separate Protocol, Security, Wellness and Commerce properties.\n\nBuilt by [David Mosiah](https://github.com/davidmosiah). The astrology engine is ported from the [Alkhemia](https://alkhemia.app) app.\n\nNew to the protocol pattern? Read **[What Is an Astrology MCP Server?](https://astral.delx.ai/guides/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.\n\nReady to calculate one? Follow **[How to Generate a Natal Chart with MCP](https://astral.delx.ai/guides/how-to-generate-a-natal-chart-with-mcp)** for the exact birthplace, timezone, unknown birth-time, payload and precision-audit workflow.\n\nHandling sensitive inputs? Read **[How to Protect Birth Data in Astrology Agent Workflows](https://astral.delx.ai/guides/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`.\n\n## Why this exists\n\nMost 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:\n\n1. **It just works.** `npx -y astral-mcp` and you're calling charts — no OAuth, no account, no birthplace database to install.\n2. **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.\n\n## Setup in 60 seconds\n\nAdd it to your MCP client (Claude Desktop, Cursor, Hermes, …):\n\n```json\n{\n \"mcpServers\": {\n \"astral\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"astral-mcp\"]\n }\n }\n}\n```\n\nThat's the whole setup. There is nothing to authenticate.\n\nRun it directly if you want:\n\n```bash\nnpx -y astral-mcp # stdio (default)\nASTRAL_MCP_TRANSPORT=http npx -y astral-mcp # streamable HTTP on 127.0.0.1:3000\n```\n\n## See it before you connect\n\nCall **`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.\n\n## Try it with your agent\n\n> \"What's my natal chart? I was born 23 Feb 1989, 14:30, in Fortaleza, Brazil.\"\n\nThe agent calls `astral_search_birthplace` to resolve Fortaleza → lat/lon/timezone, then `astral_compute_natal_chart`.\n\n> \"Any big transits hitting my chart this week?\" → `astral_current_transits`\n> \"How compatible are we?\" (two birth datas) → `astral_synastry`\n> \"What phase is the moon in today?\" → `astral_moon_phase`\n\n## Precision\n\nAstral MCP ships every natal chart with a precision audit. The primary engine ([circular-natal-horoscope-js](https://www.npmjs.com/package/circular-natal-horoscope-js)) computes the chart; the verifier ([astronomy-engine](https://www.npmjs.com/package/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.\n\nAcross 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:\n\n```bash\nnpm run test:accuracy\n```\n\n## Data availability\n\n| Capability | Supported |\n|---|---|\n| Planets (Sun…Pluto), Ascendant, MC/IC | ✅ |\n| Houses (placidus, koch, campanus, regiomontanus, topocentric, equal-house, whole-sign) | ✅ |\n| Major aspects with orb, strength, applying/separating | ✅ |\n| Chart signature (dominant element/modality, pattern, stelliums, angular planets) | ✅ |\n| Retrogrades · timezone/DST handling | ✅ |\n| Transits (current + upcoming) · moon phase | ✅ |\n| Synastry (two-chart comparison, scored) | ✅ |\n| Tropical & sidereal zodiac | ✅ |\n| Lunar nodes, Chiron, asteroids, fixed stars | ⏳ planned |\n| Minor aspects | ⏳ planned |\n| Interpretation text | ❌ by design — astral-mcp returns structured data; your model writes the reading |\n\n## Tools\n\n- `astral_compute_natal_chart` — full natal chart, precision-audited by default\n- `astral_current_transits` — current + upcoming transits to a chart, with moon phase\n- `astral_synastry` — compare two charts (harmony / chemistry / communication / growth)\n- `astral_moon_phase` — moon phase, sign and illumination for any date\n- `astral_search_birthplace` — geocode a place to latitude / longitude / timezone\n- `astral_demo` — worked example chart, no input needed\n- `astral_capabilities` — what this server supports and what it doesn't\n- `astral_data_inventory` — data domains and recommended first calls\n- `astral_agent_manifest` — install + usage rules for agents\n- `astral_connection_status` — health check via a sample chart + dual-engine audit\n\nThe 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`:\n\n- `full` (default) — the complete payload, including the per-planet precision audit\n- `structured` — same structure, redundant/derivable fields dropped\n- `summary` — only the high-signal essentials (luminaries + Ascendant, chart signature, top aspects)\n\nA 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.\n\n## Notes for accurate readings\n\n- Pass the **birthplace** timezone, not the caller's. `astral_search_birthplace` returns it.\n- `birth_time` is optional. Without it, noon is assumed: planet signs stay accurate, but the Ascendant and houses are unreliable.\n\n## Privacy & Security\n\nAstral 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](SECURITY.md).\n\n## Contributing\n\nThe computation core in `src/engine/` is ported from Alkhemia — keep it framework-free. See [AGENTS.md](AGENTS.md) for the development rules and the test gate (`npm test`).\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n## HTTP (v2 stateless)\n\nDefault is **stdio**. Optional Streamable HTTP — no session id, JSON responses, loopback only:\n\n```bash\nnpx -y astral-mcp --http\n# GET http://127.0.0.1:3000/health\n# POST http://127.0.0.1:3000/mcp (sessionless)\n```\n\nEnv: `ASTRAL_MCP_HOST`, `ASTRAL_MCP_PORT`, `ASTRAL_MCP_TRANSPORT=http`.\n\n## Skill or MCP\n\n```bash\nnpx -y astral-mcp call astral_connection_status --json '{}'\n```\n", "bytes": 8966, "sha": "e27318e753860425eee5d29fa509143bd11732c41782a6cf4c16a7b97b506ef2", "repo_slug": "davidmosiah/astral-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_davidmosiah_astral_mcp_13fc61dc/readme" }