Astral MCP Astrology for AI agents

astral.delx.ai · open source · local-first

Real astrologyyour AI can trust.

Astral MCP is a local-first bridge that gives MCP-aware agents real astrology: natal charts, transits, synastry and moon phases. Every chart is computed by one ephemeris and independently re-derived by a second, so your agent reasons over verified placements, not silent errors. No API key, no account.

Install in one command Give this to your agent
npx -y astral-mcp
  • 10 toolsagent-discoverable astrology actions
  • 2 ephemeridesevery chart cross-checked
  • 0 API keysno OAuth, no account
  • < 0.01°worst cross-engine delta
Stateless & offline. Astral MCP stores nothing and holds no secrets. The only optional network call is birthplace geocoding via OpenStreetMap, which sends just the place name you pass. Every other tool runs fully offline.
Primary siteastral.delx.ai SourceGitHub repo Installnpm package Engine originAlkhemia app

The product idea

From birth data to a chart your model can read.

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.

01

It just works

npx -y astral-mcp and you are calling charts. No OAuth, no account, no birthplace database to install.

02

It checks itself

Every natal chart is re-derived planet by planet by a second ephemeris. Disagreements beyond tolerance are flagged review, never returned silently.

03

It stays in your voice

Astral MCP returns structured data only. Your model writes the reading, so the interpretation matches your agent's tone.

Data availability

Clear about what it computes.

The computation core is ported from the Alkhemia app and kept framework-free. Here is exactly what ships, what is planned, and what is out of scope by design.

Yes

Computed today

Planets (Sun–Pluto), Ascendant, MC/IC, houses, major aspects with orb and applying/separating, chart signature (dominant element, modality, patterns, stelliums), retrogrades and timezone/DST handling.

Soon

Planned

Lunar nodes, Chiron, asteroids, fixed stars and minor aspects are on the roadmap, not yet shipped.

No

Out of scope

Interpretation text is intentionally excluded. Astral MCP returns structured data; the calling model writes the reading.

The 10 tools

Everything an agent can call.

Tool names are stable and agent-discoverable. House systems: placidus, koch, campanus, regiomontanus, topocentric, equal-house, whole-sign. Zodiacs: tropical and sidereal.

Core

astral_compute_natal_chart

Full natal chart — planets, houses, aspects, signature — precision-audited by default.

Core

astral_current_transits

Current and upcoming transits to a natal chart, with the moon phase included.

Core

astral_synastry

Compare two charts, scored across harmony, chemistry, communication and growth.

Core

astral_moon_phase

Moon phase, sign and illumination for any date — no birth data required.

Util

astral_search_birthplace

Geocode a place name to latitude, longitude and timezone via OpenStreetMap.

Util

astral_demo

A fully-worked example chart (Greenwich, noon, Y2K) with its audit — no input, no network.

Meta

astral_capabilities

What this server supports: house systems, zodiacs, bodies, aspects and limits.

Meta

astral_data_inventory

Data domains and the recommended first calls for an agent.

Meta

astral_agent_manifest

Install and usage rules written for agents to follow on first run.

Meta

astral_connection_status

Health check via a sample chart and a live dual-engine audit.

Dual-engine precision

Two ephemerides. One verified chart.

The primary engine computes the chart; the verifier 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 spanning 1945–2010 and six timezones, the worst cross-engine disagreement is under 0.01°.

Primary engine circular-natal-horoscope-js computes planets, houses and aspects.
Independent verifier astronomy-engine re-derives each planet's longitude from scratch.
Fail loud, not silent Disagreements are flagged review, so a wrong placement is never returned as fact.
Diagram: birth data flows into a primary ephemeris and a verifier ephemeris; the cross-check returns a verified chart or flags it for review

Questions people ask first

Precise answers before anyone installs.

A trustworthy astrology bridge should be explicit about setup, accuracy, and where the model's job begins.

Does it need an API key or account?

No. Run npx -y astral-mcp and start calling charts immediately — no OAuth, no account, no birthplace database to install. The only optional network call is birthplace geocoding via OpenStreetMap.

What does the precision audit do?

Every chart is computed by circular-natal-horoscope-js and re-derived planet by planet by astronomy-engine. It is verified only when every planet agrees within tolerance and shares the same sign; otherwise it is flagged review.

What should my agent call first?

Start with astral_capabilities, then astral_search_birthplace to resolve a city, then astral_compute_natal_chart. Go deeper with transits, synastry or moon phase.

Does it write the interpretation?

No, by design. It returns structured data (planets, houses, aspects, signature, audit). Your model writes the reading, so it stays in your agent's voice. Pass the birthplace timezone, not the caller's, and include birth_time for an accurate Ascendant and houses.

Read the llms.txt Full README

Zero-setup install

Install it in about 60 seconds.

There is nothing to authenticate. Add one MCP server to your client and start calling tools. Works in Claude Desktop, Cursor, Hermes and any client that speaks MCP over stdio.

Path A

I am a human

Add the MCP config below to your client, reload, then call astral_demo to see a worked chart before sending real birth data.

Path B

I want my agent to help

Copy the delegation prompt below. It tells your assistant exactly what to install and how to verify the connection safely.

Jump to agent prompt
Step 1

Run it directly (optional)

Want to try it from a terminal first? Run it over stdio, or switch to streamable HTTP with one environment variable.

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

Nothing is stored and no credentials exist. Every tool but optional geocoding runs fully offline.

Step 2

Add the MCP config to your client

Use it with Claude Desktop, Cursor, Windsurf, Hermes, OpenClaw or any client that supports MCP over stdio.

Claude Cursor Windsurf Hermes OpenClaw Generic MCP 
{
  "mcpServers": {
    "astral": {
      "command": "npx",
      "args": ["-y", "astral-mcp"]
    }
  }
}

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

Step 3

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 the exact payload shape before you send real birth data.

Show the payload-verbosity modes
full complete payload + per-planet precision audit (~6.9 KB)
structured same shape, derivable fields dropped
summary luminaries + Ascendant + signature + top aspects (~1.2 KB)

Prompts that feel natural

Ask in plain language.

Your agent resolves the birthplace, computes the chart, and reasons over verified placements. Try these.

Natal

Read my chart

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

Transits

What's hitting now

Any big transits hitting my chart this week? Use my birth data and tell me what to watch.

Synastry

Compare two people

How compatible are we? Here are two birth datas — score our harmony, chemistry, communication and growth.

Moon

Today's moon

What phase is the moon in today, what sign is it in, and how illuminated is it?

Trust boundary

Nothing stored. No secrets.

Astral MCP is stateless and computational. There are no credentials to leak because none exist, and the only data that ever leaves your machine is a place name — and only if you call geocoding.

Stateless

Nothing is written to disk and no history is kept between calls.

No keys

No API key, no OAuth, no account. There is nothing to authenticate or rotate.

Offline by default

Every tool but optional geocoding runs without any network access.

Minimal egress

astral_search_birthplace sends only the place-name string to OpenStreetMap.

For AI agents

A delegation prompt that does not guess.

If a non-technical user wants their assistant to install the bridge, this prompt gives the agent enough structure to proceed and verify safely.

Install the Astral MCP server for me.
Repository: https://github.com/davidmosiah/astral-mcp
npm package: astral-mcp  (no API key, no account)

Add this MCP config to my client:
{ "mcpServers": { "astral": { "command": "npx", "args": ["-y", "astral-mcp"] } } }

After reloading MCP:
- call astral_agent_manifest and astral_capabilities to learn the contract
- call astral_connection_status to confirm the audit returns "verified"
- call astral_demo and show me the worked example chart

For builders

Open source, with a clear edge.

Built by David Mosiah for people building practical AI-agent systems. The astrology engine is ported from the Alkhemia app and kept framework-free, so the computation core in src/engine/ is easy to understand and reuse.

MIT licensed. Run the accuracy suite yourself with npm run test:accuracy and the full gate with npm test.

Open an issue Dev rules npm package

Open source astrology agents

Give your agent a sky it can trust.

Star the repo, inspect the engine, open issues or adapt the bridge for your own agent workflow.

Open GitHub npm package MCP Registry