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.

More tools (transits, synastry, compatibility, moon phases, 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