AstroWay MCP is the official MCP server for the AstroWay Calculation API, exposing astrology-related calculation endpoints as directly callable tools for Claude Desktop, Cursor, Windsurf, and any MCP-compatible AI agent.
Purpose It enables AI clients to directly call astrology calculation capabilities, including natal charts, synastry, transits, Vedic Dasha (Vimshottari, Yogini, Ashtottari, Kalachakra), 16 Vargas, tarot (Rider-Waite / Marseille / Lenormand), numerology (5 systems), Human Design, AI horoscopes, and more.
Key capabilities
- Tools are automatically generated by a build-time script that reads the canonical endpoint list of the production API, classifies them by input shape (chart, twoChart, chartTarget, horoscopeSign, year, date, generic), and generates typed tool definitions registered as MCP Tools with Zod input schemas. When the API adds new endpoints, the next MCP version automatically includes them, with no manual synchronization of tool definitions required.
- Supports subset registration: register only some tool groups via ASTROWAY_TOOL_GROUPS. Common groups include western, vedic, tarot, numerology, hd (Human Design), relational (synastry/composite/davison), prognostics (transits/progressions/returns), aspects, horary, geo, chinese, bazi, mayan, iching, runes, geomancy. Use npx @astroway/mcp --list-tools to view the full tool set.
- ASTROWAY_READONLY=1 skips the three groups that internally call an LLM (ai, horoscope, reports), suitable for scenarios that only perform deterministic chart calculations and do not consume text generation quota.
- Discovery (lean) mode: after setting ASTROWAY_DISCOVERY_MODE=1, instead of pre-registering 600+ tools, only two meta-tools are exposed: astroway_find_tool(query, limit?) is used to keyword-search the entire catalog and return the best-matching tools along with their one-line descriptions and input parameter names; astroway_call_tool(name, arguments?) is used to call any tool found via search. The trade-off is that calls dispatched via astroway_call_tool return only text results and cannot carry the validated structuredContent provided by directly registered tools. Discovery mode overrides ASTROWAY_TOOL_GROUPS / ASTROWAY_READONLY.
- The catalog is frozen during a session: tools, prompts, and resources are all bundled in the published npm package and do not change at runtime. Tool identifiers are stable within the same major version, and input shapes are stable within the same version; breaking changes in major version upgrades are announced, with MCP_FLAT_TOOLS=1 provided as a transition. Reinstalling (npm i -g @astroway/mcp@latest or npx -y @astroway/mcp) refreshes the catalog.
Usage Add the configuration in ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows. After restarting Claude Desktop, the astroway server will appear in the MCP indicator at the bottom of the chat input box. Cursor can add it to ~/.cursor/mcp.json. Clients such as Cline / Continue / Windsurf / Copilot / VS Code MCP also use the npx @astroway/mcp command, placed in their respective MCP configuration files. It can also be run as a stdio server.
Verifying the installation: after restarting the MCP client, open the MCP indicator; astroway should be listed as an active server, and hovering over or clicking it should show the number of registered tools, prompts, and resources; npx @astroway/mcp --list-tools prints the full tool list for the current version. The first cold start takes about 2-3 seconds (Node + TLS handshake to api.astroway.info). In the terminal, you can use npx @astroway/mcp --version to check the version, and npx @astroway/mcp --list-tools synastry to view the matching tools. If the server does not appear, you can set LOG_LEVEL=debug in env and restart; the startup line and errors will appear in the client's MCP debug panel.
Example prompts include: calculate the natal chart for a specified birth time and place and identify the Sun, Moon, Ascendant, and tight aspects; compare the strongest cross-aspects between two charts; run the Vimshottari Mahadasha and determine the current planetary period; query the major outer planet transits hitting the natal chart on a specified date; draw three past-present-future cards using a Rider-Waite spread and specify a seed; query Human Design type, strategy, authority, defined centers, and incarnation cross; use astroway_mcp_ai_chat to ask about the meaning of Saturn's position and require citation of houses and aspect orbs.
Use cases Suitable for users who need astrology, Vedic astrology, tarot, numerology, Human Design, and other calculations in an AI client, as well as developers who want to integrate astrological calculations into their own agents via MCP.
Limitations and notes This MCP server does not report telemetry, analytics, or usage data. The only network traffic is the AstroWay API calls requested by the user, sent directly from the local machine to https://api.astroway.info/v1。出站请求带两个标识头：User-Agent: astroway-mcp/<version> (Node/<node-version>) and X-Astroway-Channel: mcp, neither of which contains session IDs, machine fingerprints, or personal information.
To use it, you need to register at https://api.astroway.info/dashboard/sign-up . It is free and provides 10,000 credits per month, with no credit card required; each request consumes 5–500 credits, depending on the endpoint. For local testing, you can use a sandbox key (aw_test_...), which returns deterministic responses for free. Common errors: 401 means the API key is missing, invalid, or revoked; 402 means the free quota is exhausted; 422 means request body field validation failed.
This repository is the public showcase page for @astroway/mcp (README, CHANGELOG, LICENSE, installation instructions). The runnable code is the published npm package. The source code is maintained in a private AstroWay monorepo, and the generated package is open-sourced under the MIT license and released to npm with each release.
