MCP Server: Use AstroAPI from AI Assistants

AstroAPI ships a hosted Model Context Protocol (MCP) server. Connect it to an AI assistant like Claude Code, Claude Desktop or Cursor, and the assistant can call AstroAPI directly — look up birth places, calculate charts and explain the results in plain language.

This is also the fastest way to build an integration: connect the MCP server to your AI coding assistant and ask it to write the integration code for you. The assistant can make real API calls while it works, so it sees actual responses instead of guessing.

No code required

Once connected, you can simply ask your assistant things like "Calculate the natal chart for someone born on June 15th 1990 at 2:30pm in Amsterdam" — the assistant resolves the location, calls the API and summarizes the result.

---

Endpoint

https://mcp.astroapi.cloud/mcp

• Transport: Streamable HTTP
• Authentication: your regular AstroAPI key, sent as the X-Api-Key header
• Your subscription's modules, rate limits and quotas apply exactly as they do for direct API calls.

You can create an API key in the dashboard under API Keys. See Authentication for details.

---

Connect Claude Code

Run this once in your terminal:

claude mcp add --transport http astroapi https://mcp.astroapi.cloud/mcp \
  --header "X-Api-Key: YOUR_API_KEY"

Then just ask Claude Code to use AstroAPI — for example: "Use the astroapi tools to calculate a natal chart for 1990-06-15 14:30 in Amsterdam and build me a React component that displays it."

Connect Cursor

Add this to .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "astroapi": {
      "url": "https://mcp.astroapi.cloud/mcp",
      "headers": {
        "X-Api-Key": "YOUR_API_KEY"
      }
    }
  }
}

Connect other MCP clients

Any client that supports MCP over Streamable HTTP with custom headers works. Configure:

Setting	Value
URL	https://mcp.astroapi.cloud/mcp
Transport	Streamable HTTP
Header	X-Api-Key: YOUR_API_KEY

Hosted clients without custom headers

Some hosted clients (such as claude.ai web connectors) cannot send custom headers and require OAuth. OAuth support is on the roadmap; for now, use a client that supports custom headers, like Claude Code, Claude Desktop or Cursor.

---

Available Tools

Tool	What it does
astro_resolve_place	Looks up a place name and returns coordinates and the IANA timezone. Assistants are instructed to call this first, so they never guess coordinates.
astro_natal_chart	Calculates a natal chart (points, houses, aspects), optionally with interpretation texts, and returns a compact readable summary.
astro_synastry	Compares two birth charts and lists the inter-chart aspects in both directions.
astro_composite	Calculates a composite (midpoint) relationship chart with its own positions and aspects.
astro_transits	Finds transits over a natal chart in a period (up to 2 years): start, exact and end dates per aspect.
astro_compatibility	Quick Sun-sign compatibility score between two people.
astro_solar_return	The solar return chart for a given year (the astrological birthday chart).
astro_lunar_return	The lunar return chart from a given date (roughly monthly).
astro_progressions	Secondary progressions for a target date, including aspects to the natal chart.
astro_human_design	A full Human Design bodygraph: Type, Strategy, Authority, Profile, centers, channels and gates.
astro_moon_sun	Moon phase plus rise/set, solar noon and twilight times for a date and place.
astro_moon_calendar	Day report (sign, phase, void-of-course) or a range overview of phases, sign changes and void periods.
astro_retrograde_calendar	Retrograde periods with station dates, signs traversed and shadow periods.
astro_chinese_horoscope	Chinese zodiac sign and element, or a yearly forecast.
astro_numerology	The full numerology profile from a birth date and name, or just the Life Path number.
astro_numerology_compatibility	Compatibility between two people based on their Life Path numbers.
astro_horoscope	Pre-written daily, weekly, yearly and yearly-Ascendant horoscope reports.
astro_ai_summary	Writes a short narrative summary of what a horoscope means, from the strongest placements and aspects of the chart. Requires the AI Summary module.

More tools (astrocartography, chart images and others) are on the way. Tool availability follows your subscription's modules: a tool that your plan doesn't include returns a clear message instead of data.

---

Example Session

A conversation with a connected assistant might look like this:

You: What's the sun sign and ascendant for someone born March 3rd 1985 at 6:45 in Barcelona?

Assistant: calls astro_resolve_place with "Barcelona", then astro_natal_chart with the resolved coordinates and timezone — The Sun is in Pisces at 12°41′ in the 1st house, and the Ascendant is Aquarius 28°10′ …

The assistant handles geocoding, timezone conversion and the API call — the things that usually go wrong when entering birth data by hand.

---

Next Steps

• Authentication — create and manage API keys
• Getting Started — the API basics behind these tools
• Natal Charts — what the natal calculation returns