Claude Desktop

Connect the AstroWay API to Claude Desktop over MCP: as a one-click extension, or by hand through the config file with the hosted (HTTP) server or the local stdio package.

Prerequisites

Get an API key in the dashboard. For free testing use a sandbox aw_test_* key - it doesn’t spend credits.

One-click extension

1. Download astroway.mcpb.
2. Open the file. Claude Desktop shows the install dialog.
3. Paste your API key, pick the tool groups (the default covers natal charts, transits, progressions, returns, synastry and the calendar), and enable it.

No config file to edit. The extension is the npm package @astroway/mcp with its dependencies, built from the same release. Clear the tool groups field to load all 700+ tools.

Setup by hand

Open Settings → Developer → Edit Config - Claude Desktop reveals the path to claude_desktop_config.json. Paste one of the blocks below and restart Claude Desktop.

Hosted (HTTP): no package of ours to install, Bearer-token auth. Claude Desktop’s config file only starts local commands and skips an entry with a bare url, so the hosted server goes through the mcp-remote bridge:

claude_desktop_config.json

{
"mcpServers": {
  "astroway": {
    "command": "npx",
    "args": ["-y", "mcp-remote", "https://mcp.astroway.info/mcp", "--header", "Authorization:${AUTH_HEADER}"],
    "env": { "AUTH_HEADER": "Bearer aw_live_YOUR_KEY" }
  }
}
}

The key sits in env rather than in args because Claude Desktop on Windows breaks an argument at the space after Bearer. To load one subject instead of the whole catalogue, replace /mcp with a domain server such as /mcp/core or /mcp/vedic.

Stdio (npx): local subprocess, env-var auth, offline-ready:

claude_desktop_config.json

{
"mcpServers": {
  "astroway": {
    "command": "npx",
    "args": ["-y", "@astroway/mcp"],
    "env": { "ASTROWAY_API_KEY": "aw_live_YOUR_KEY" }
  }
}
}

Verify

Tell Claude in chat: “List the AstroWay tools” - or ask it to call a free reference tool, such as fetching the list of zodiac signs. If a result comes back, the connection works.

Troubleshooting

• 401 / invalid key: make sure the key is prefixed aw_live_* or aw_test_* and isn’t revoked. Check it in the dashboard.
• “Some MCP servers couldn’t be loaded”: the entry has url instead of command. Use the mcp-remote block above.
• Tools don’t appear: fully restart Claude Desktop (quit it, don’t just close the window) and verify the path to claude_desktop_config.json.
• -32602 validation errors (stdio): update the package: npm i @astroway/mcp@latest. Schemas are regenerated from the live spec.

See all clients - Agent setup.