FreeAstroAPI Astrology

Hosted MCP

Connect FreeAstroAPI directly to AI tools through a hosted MCP server. You do not need to install a local server, run a script, or build anything first. Add one URL, add your API key, reconnect your AI tool, and it can start calling astrology endpoints as tools.

Best for AI-first users: if your app offers “Remote MCP”, “Hosted MCP”, or “Streamable HTTP MCP”, choose that option. If it only asks you for a terminal command, that app is expecting a local stdio server instead.

MCP Server URL

HTTPhttps://api.freeastroapi.com/mcp

Claude Desktop: one-click extension

Claude Desktop's Custom Connector form cannot add the x-api-key header. Install this desktop extension instead. It asks for your FreeAstroAPI key during setup and requires no terminal commands.

Download for Claude Desktop (.dxt)

/downloads/mcp/freeastroapi-claude-desktop.dxt

Install in four steps

1. Download the extension file.
2. Open Claude Desktop → Settings → Extensions → Advanced settings.
3. Choose Install Extension and select the downloaded file.
4. Paste your API key, then enable FreeAstroAPI under Search and tools.

1. Add the server

In your AI app, create a new remote MCP server and paste the URL from this page.

2. Add your API key

Send your key as the x-api-key header. The MCP server uses the same key and limits as the normal API.

3. Start asking

Once connected, your AI can discover tools and call them directly instead of guessing astrology data.

Quick Setup

AI app setupcURLNode.js

Name: FreeAstroAPI
Type: Remote / Hosted MCP server
URL: https://api.freeastroapi.com/mcp

Header:
x-api-key: YOUR_API_KEY

What Your AI Gets

Lookup and utility tools

• City Search
• Moon Phase
• Moon Phase Timeline
• Ephemeris
• Daily horoscope endpoints

Chart and astrology tools

• Natal chart calculation
• Transits
• Western synastry
• Vedic chart endpoints
• Chinese BaZi endpoints

Authentication, billing, admin, webhooks, and account-management endpoints are intentionally excluded from MCP.

Good Prompts To Try

Search Paris, France and give me the exact timezone and coordinates.

Calculate a natal chart for June 1, 1990 at 14:30 in New York.

Show me the current moon phase and explain it in simple language.

Get a weekly ephemeris table for Venus and Mars in tropical zodiac.

Authentication

Field	Value	Notes
Header	x-api-key	Use the same API key you already use for REST requests.
Tier behavior	same as REST	MCP is included on every tier, but calls still count against your normal usage and RPS limits.
Transport	Streamable HTTP	Choose a remote or hosted MCP option in your AI tool.

Advanced: Raw MCP Calls

Most users will never need this. It is here for advanced tools, testing, and debugging.

Initialize

curl -X POST "https://api.freeastroapi.com/mcp" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {
        "name": "example-client",
        "version": "1.0.0"
      }
    }
  }'

Call a Tool

curl -X POST "https://api.freeastroapi.com/mcp" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "v2_geo_search",
      "arguments": {
        "q": "paris",
        "limit": 3
      }
    }
  }'

Sample Response

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"results\": [ ... ],\n  \"count\": 3\n}"
      }
    ],
    "structuredContent": {
      "results": [
        {
          "name": "Paris",
          "country": "FR",
          "lat": 48.85341,
          "lng": 2.3488,
          "timezone": "Europe/Paris",
          "population": 2138551
        }
      ],
      "count": 1
    },
    "metadata": {
      "status_code": 200,
      "path": "/api/v2/geo/search",
      "method": "GET"
    }
  }
}

Troubleshooting

Claude Desktop's Custom Connector rejects this setup. Download the Claude Desktop extension above. The URL-only connector form cannot send the required x-api-key header.

I only see “command” setup, not URL setup. That app expects a local stdio MCP server. Use an app that supports remote or hosted MCP.

The server connects but tools fail. Check that your API key is valid and has not expired. MCP uses the same key and limits as the normal API.

My AI says rate limited. MCP calls count exactly like direct API requests. Check Rate Limits.

I need coordinates first. Ask the AI to use City Search before requesting a natal, transit, or synastry chart. The AI can do that through MCP automatically.

Related Docs

Authentication

Generate and manage API keys.

Rate Limits

How quotas and retry windows work.

City Search

The most useful first tool for AI workflows.

Get an API Key