AstroMCP Console Setup

What this is

AstroMCP is your astrology companion: exact chart calculations, saved charts, and a clean toolset that your AI can call on demand.

This guide is intentionally "hold your hand" detailed for demo day.

Before you start

1. Make sure you can open the console:

• Sign in to AstroMCP
• Go to /console
• If you can see the page, you have access

2. Create an API key (for MCP / local tools):

• Go to /dashboard/api-keys
• Create a key and copy it

Quick map (how the tools work)

Paste this into any Mermaid renderer (for example, Mermaid Live) to visualize the AstroMCP tool flow:

flowchart TD
  U[User text: \"June 1 1990 2:15pm in Austin, TX\"] --> P[parse_birth_info]
  P --> Z[resolve_datetime_location]
  Z --> N[calculate_natal]
  N --> S[(Save primary chart)]

  S --> L[my_saved_charts]
  L --> R[recall_chart (by label or id)]
  L --> D[delete_chart (by label or id)]

  N --> T[calculate_transit]
  N --> C[compare_natal_transit]

The 10 AstroMCP tools

1. parse_birth_info - Extract date, time (required), and location from natural language.
2. geocode_location - Turn a location string into coordinates (includes timezone when available).
3. resolve_datetime_location - Normalize datetime + location into coordinates + IANA timezone + UTC offset (DST-aware). Use this before chart calls to avoid silent timezone mistakes.
4. calculate_natal - Compute a natal chart (Whole Sign default unless you changed your preference). Requires timezone (call resolve_datetime_location if you don't have it).
5. calculate_transit - Compute current transits for a location. Requires timezone.
6. compare_natal_transit - Compare natal vs current sky. Requires timezone.
7. my_saved_charts - List labels only (privacy-first).
8. recall_chart - Load a saved chart by label or id.
9. save_chart - Save any chart with a label (+ optional tags).
10. delete_chart - Delete by label or id.

Setup A: Cursor (recommended)

Cursor supports a one-click MCP install deep link. On /console, use:

• "Add to Cursor"
• Then replace astro_YOUR_KEY_HERE with your real API key

If you need to do it manually, Cursor stores MCP configuration in a JSON file:

| OS | Path | | --- | --- | | macOS | ~/.cursor/mcp.json or ~/Library/Application Support/Cursor/User/globalStorage/mcp.json | | Windows | %APPDATA%\\Cursor\\User\\globalStorage\\mcp.json | | Linux | ~/.config/cursor/User/globalStorage/mcp.json |

Create the file if it doesn't exist, then paste:

{
  "mcpServers": {
    "astromcp": {
      "command": "npx",
      "args": ["-y", "@astromcp-dev/mcp-server"],
      "env": {
        "ASTROMCP_PROFILE": "astromcp",
        "ASTROMCP_BACKEND_URL": "https://api.astromcp.io",
        "ASTROMCP_API_KEY": "astro_YOUR_KEY_HERE",
        "MCP_USER_ID": "YOUR_USER_ID"
      }
    }
  }
}

Then:

1. Restart Cursor (fully quit and reopen)
2. In chat, try:

Use AstroMCP to parse_birth_info for: "June 1 1990 2:15pm in Austin, TX"

If it responds with structured fields, you're connected.

Setup B: Claude Desktop (MCP)

Claude Desktop reads an MCP server config file:

| OS | Path | | --- | --- | | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\\Claude\\claude_desktop_config.json |

Safest approach:

1. Open Claude Desktop settings
2. Go to Developer -> Edit config (or MCP / Servers)
3. Paste the config (or merge it into the existing JSON)

Paste the same mcpServers.astromcp config used for Cursor.

Then restart Claude Desktop and test with the same prompt.

Setup C: ChatGPT (Custom GPT Actions) — OAuth coming soon

We are rebuilding the ChatGPT Actions experience on OAuth instead of the legacy token/session handshake. Until that flow ships, continue using Cursor or Claude Desktop (see the earlier sections) or call the REST endpoints directly with your current Supabase session token by copying the OpenAPI schema and posting to /api/consumer/* with Authorization: Bearer <session>. Once OAuth is ready we’ll update this section with the new workflow so you can install the GPT without manually exchanging tokens.

Troubleshooting (common)

• "Forbidden": your account does not have access yet.
• "Unauthorized": the session token expired. Rerun Step 5 to refresh it (the long-lived token remains the same).
• Cursor/Claude shows no tools: fully quit and reopen the app after editing the MCP config.