Agent infrastructure · practical guide

What is an astrology MCP server?

Q: Is an astrology MCP server the same as an astrology API?

Not exactly. Both expose computed astrology data, but MCP publishes tool schemas and results in a protocol designed for AI clients. Astral MCP can run locally without an API account.

Q: Does Astral MCP generate horoscope prose?

No. It returns structured astrology data only; the calling model writes the explanation or reading.

Q: Can it calculate a chart without an exact birth time?

Yes, but noon is assumed. Planetary signs remain usable while the Ascendant and houses must not be treated as reliable.

A precise division of labor: deterministic software computes the chart, an MCP tool carries structured data, and the language model explains the result.

Updated 11 Aug 20269 minute readMarkdown for agents

Direct answer

An astrology MCP server connects an AI agent to deterministic astrology tools through the Model Context Protocol. Instead of asking a language model to guess planetary positions, the agent calls named tools that compute a natal chart, transits, synastry or a moon phase and return structured data for the model to explain.

Astral MCP is an open-source, local-first implementation. It needs no API key or account, birth data is not persisted, and it returns structured astrology data only.

The important separation

Computation is not interpretation.

An astrology workflow has three distinct jobs. Keeping them separate makes the result easier to inspect, reproduce and explain.

Engine computes

Deterministic code turns date, time, coordinates and timezone into planets, houses, aspects and derived chart fields.

MCP transports

Named tools publish explicit input and output schemas so an agent knows what to call and what came back.

Model explains

The calling model writes the interpretation in the desired voice without inventing the underlying placements.

Recommended workflow

From a city name to a bounded reading.

Call only the tools the question needs. A smaller sequence is easier to audit and sends less birth data through model context.

Discover capabilitiesCall astral_capabilities to learn supported bodies, aspects, zodiacs, house systems and limits.
Resolve the birthplaceCall astral_search_birthplace for latitude, longitude and the birthplace timezone.
Compute the natal chartCall astral_compute_natal_chart and inspect the precision-audit status before interpreting it.
Go deeper only when askedUse astral_current_transits, astral_synastry or astral_moon_phase for a matching follow-up.
Explain with the limits attachedThe model interprets the structured result and discloses missing birth-time or advice boundaries.

Precision boundary

Two engines can catch a silent placement error.

Every Astral MCP natal chart is computed by circular-natal-horoscope-js. Planetary longitudes are independently re-derived with astronomy-engine.

A chart is marked verified only when every checked planet agrees within tolerance and remains in the same sign. A disagreement is flagged for review instead of silently accepted.

That verifies computational agreement. It does not turn an astrological interpretation into scientific, clinical or predictive fact.

Birth data enters two independent ephemeris engines; agreement produces a verified chart and disagreement produces review status — Primary computation and independent verification stay visible as separate steps.

Privacy and accuracy boundary

Local-first does not mean context-free.

The server stores nothing, but the user and client still decide which birth data enters an agent conversation.

No persistence

Birth data is not persisted. Astral MCP is stateless and writes no reading history.

No secrets

There is no API key, OAuth flow or account. Chart tools run locally.

One optional egress

Birthplace search sends only the place-name string to OpenStreetMap.

Compact mode

Use privacy_mode=summary when the agent only needs luminaries, Ascendant, signature and top aspects.

Unknown birth time: noon is assumed. Planetary signs remain usable, but the Ascendant and houses are unreliable and must be described that way.

Try the implementation

One command, then a worked demo.

After your MCP client reloads, call astral_connection_status and then astral_demo before sending real birth data.

npx -y astral-mcp

Decision guide

When this pattern fits.

Use an astrology MCP server when

The agent needs reproducible chart computation.
Inputs and outputs should have explicit schemas.
Local execution and inspectable source matter.
The model should write the reading in its own voice.

Do not treat it as

A substitute for medical or psychological care.
Evidence for a financial or legal decision.
A guarantee about future events.
A reliable Ascendant when birth time is unknown.

Astral MCP is not financial, medical, legal or psychological advice. It provides structured astrology data for agent workflows.

Frequently asked

Short answers for builders and agents.

Is an astrology MCP server the same as an astrology API?

Not exactly. Both can expose computed data, but MCP publishes tool schemas and results in a protocol designed for AI clients. Astral MCP runs locally over stdio or loopback HTTP without an API account.

Does Astral MCP generate horoscope prose?

No. It returns structured astrology data only. The calling model writes the explanation, reading or narrative.

Can it calculate a chart without an exact birth time?

Yes, with a disclosed limit. Noon is assumed, so the Ascendant and houses must not be treated as reliable.

Is birth data uploaded or stored?

No reading history is stored. Only an optional birthplace lookup sends the place-name string to OpenStreetMap; chart computation remains local.

Canonical implementation

Inspect the tool before trusting the reading.

Astral MCP is open source, MIT licensed and ships its accuracy suite with the repository. Ready to use the pattern? Follow the step-by-step natal chart MCP workflow, then read the birth-data privacy workflow.

Generate a natal chart Read the source Open npm