astroway/astroway-mcp

> MCP (Model Context Protocol) server exposing **every endpoint of the AstroWay Calculation API** as tools for Claude Desktop, Cursor, and any MCP-compatible AI agent.
Natal charts, synastry, transits, Vedic dashas (Vimshottari, Yogini, Ashtottari, Kalachakra), 16 Vargas, Tarot (Rider-Waite / Marseille / Lenormand), Numerology (5 systems), Human Design, AI horoscopes, all wrapped as MCP tools that the agent can call directly.
Tools are auto-generated from the live API manifest at build time, so each release ships every endpoint that exists in production. No manual tool-list maintenance.
---
Install
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
Restart Claude Desktop. The astroway server will appear in the MCP indicator at the bottom of the chat input.
Cursor
Add to ~/.cursor/mcp.json:
Cline / Continue / Windsurf / Copilot / VS Code MCP
The same npx @astroway/mcp command works in every MCP-compatible client. Drop this block into the client's MCP config file (the path varies by client):
Config locations:
| Client | Config path |
|---|---|
| **Cline** (VS Code) | .cline/mcp.json in the workspace root |
| **Continue** | ~/.continue/config.json (under mcpServers) |
| **Windsurf** | ~/.codeium/windsurf/mcp_config.json |
| **GitHub Copilot Chat (VS Code)** | enable preview in settings, then mcp.json in workspace |
| **VS Code MCP extension** | ~/.vscode/mcp.json |
Other MCP clients
Run as a stdio server:
Privacy
This MCP server **does not phone home**. There is no telemetry, no analytics, no usage reporting, and no opt-in / opt-out toggle to maintain. The only network traffic the server originates is the AstroWay API calls you ask it to make, going directly from your machine to https://api.astroway.info/v1.
Outgoing requests carry two identifying headers so the AstroWay backend can distinguish MCP traffic from raw HTTP traffic in its own logs:
- User-Agent: astroway-mcp/ (Node/ )
- X-Astroway-Channel: mcp
Neither header carries a session ID, machine fingerprint, or anything personal. They mirror standard HTTP User-Agent semantics: every CLI tool sends similar information already.
Subset registration (advanced)
If you only use part of the catalogue, you can register a subset and keep your LLM context window lean:
Common groups: western, vedic, tarot, numerology, hd (Human Design), relational (synastry/composite/davison), prognostics (transits/progressions/returns), aspects, horary, geo, chinese, bazi, mayan, iching, runes, geomancy. Run npx @astroway/mcp --list-tools to inspect the full set; the boot-line filters: … field shows what was applied.
ASTROWAY_READONLY=1 skips the three groups that internally call an LLM (ai, horoscope, reports), useful when you want pure deterministic chart math without burning credits on text generation.
Discovery (lean) mode
If your agent hits context or tool-count limits with the full catalogue, set ASTROWAY_DISCOVERY_MODE=1. Instead of registering 600+ tools up front, the server exposes just two meta-tools:
- **astroway_find_tool(query, limit?)**: keyword-search the whole catalogue; returns the best-matching tools with their one-line description and input parameter names.
- **astroway_call_tool(name, arguments?)**: invoke any tool the search surfaced.
The agent discovers the right tool on demand, then calls it, reaching the entire catalogue from a two-tool footprint.
Trade-off: a tool dispatched through astroway_call_tool returns its result as **text only**. A runtime-dispatched call cannot declare a per-call outputSchema, so it can't carry the validated structuredContent that directly-registered tools provide. Leave ASTROWAY_DISCOVERY_MODE unset (the default) when you want typed structured output; use it when tool-count pressure matters more. Discovery supersedes ASTROWAY_TOOL_GROUPS / ASTROWAY_READONLY.