https://github.com/astroway/astroway-mcp
Official MCP server for the AstroWay Calculation API — astrology tools for Claude Desktop, Cursor, Windsurf and any MCP client. Auto-generated from the live OpenAPI spec: natal charts, synastry, transits, Vedic dashas, Tarot, Human Design, AI horoscopes via Model Context Protocol.
https://github.com/astroway/astroway-mcp
ai-tools api astrology astroway claude claude-code claude-desktop cursor horoscope human-design llm mcp model-context-protocol natal-chart swiss-ephemeris synastry tarot vedic-astrology
Last synced: 25 days ago
JSON representation
Official MCP server for the AstroWay Calculation API — astrology tools for Claude Desktop, Cursor, Windsurf and any MCP client. Auto-generated from the live OpenAPI spec: natal charts, synastry, transits, Vedic dashas, Tarot, Human Design, AI horoscopes via Model Context Protocol.
- Host: GitHub
- URL: https://github.com/astroway/astroway-mcp
- Owner: astroway
- License: mit
- Created: 2026-05-06T22:17:47.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-27T12:18:05.000Z (27 days ago)
- Last Synced: 2026-05-27T14:15:04.610Z (27 days ago)
- Topics: ai-tools, api, astrology, astroway, claude, claude-code, claude-desktop, cursor, horoscope, human-design, llm, mcp, model-context-protocol, natal-chart, swiss-ephemeris, synastry, tarot, vedic-astrology
- Language: TypeScript
- Homepage: https://api.astroway.info/docs/
- Size: 92.8 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# @astroway/mcp
> MCP (Model Context Protocol) server exposing **every endpoint of the [AstroWay Calculation API](https://api.astroway.info)** as tools for Claude Desktop, Cursor, and any MCP-compatible AI agent.
[](https://www.npmjs.com/package/@astroway/mcp)
[](https://www.npmjs.com/package/@astroway/mcp)
[](LICENSE)
[](https://modelcontextprotocol.io)
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):
```json
{
"mcpServers": {
"astroway": {
"command": "npx",
"args": ["-y", "@astroway/mcp"],
"env": {
"ASTROWAY_API_KEY": "aw_live_..."
}
}
}
}
```
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`:
```json
{
"mcpServers": {
"astroway": {
"command": "npx",
"args": ["-y", "@astroway/mcp"],
"env": { "ASTROWAY_API_KEY": "aw_live_..." }
}
}
}
```
### Other MCP clients
Run as a stdio server:
```bash
ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp
```
---
## Get an API key
Sign up at — **10 000 credits/month free**, no card required. Each request costs 5–500 credits depending on the endpoint (see [pricing](https://api.astroway.info/pricing/)).
For local testing without a paid plan, use a sandbox key (`aw_test_...`) which returns deterministic responses for free.
---
## What you get
Tool categories — examples below. Run `npx @astroway/mcp` once and ask the agent *"list astroway tools"* for the full live inventory (the package auto-syncs with the API on every release).
| Category | Examples |
|---|---|
| **Core** | natal chart, planet positions, draconic, harmonics |
| **Comparisons** | synastry, composite, davison, cross-system compatibility |
| **Prognostics** | transits, secondary progressions, solar/lunar return, transit calendar |
| **Specialized Charts** | heliocentric, sidereal, eclipse search |
| **Aspects & Points** | aspects table, antiscia, midpoints, Arabic parts, fixed stars |
| **Calendar & Cycles** | retrograde periods, ingresses, lunar phases, planetary hours |
| **Dignities & Receptions** | essential dignities, almuten, hyleg, dispositors |
| **Horary** | horary chart, moon void-of-course, via combusta |
| **Human Design** | full chart, transits, penta, dream rave, hologenetic profile |
| **Astro-Geography** | astrocartography, local space, relocation chart |
| **Vedic** | 16 Vargas, Panchang, Shadbala, 4 Dasha systems × 5 levels (Vimshottari / Yogini / Ashtottari / Kalachakra), Yogas, Doshas, Compatibility, Muhurat |
| **Tarot** | Rider-Waite-Smith, Marseille, Lenormand decks; spreads + card lookups |
| **Numerology** | Pythagorean, Chaldean, Kabbalistic, Vedic, Destiny Matrix |
| **Esoteric** | I Ching, sabian symbols, fortune dice, color & gemstone correspondences |
| **Reference** | signs, planets, houses, aspects, nakshatras, Hellenistic Lots |
| **AI Interpretations** | natal, synastry, transits — Ukrainian/English |
| **Horoscope** | daily, weekly, monthly, compatibility (zodiac sign-based) |
---
## Example prompts
After connecting the server, try these in Claude Desktop:
**Natal chart**
> Calculate a natal chart for me — born 1990-03-15 at 14:30 in Kyiv, Ukraine (50.45N 30.52E, UTC+2). Identify my sun, moon, ascendant, and any tight aspects.
**Synastry**
> Compare two charts: person A born 1988-06-10 09:15 in London (51.51N -0.13E UTC+1), person B born 1991-11-22 22:40 in Berlin (52.52N 13.40E UTC+1). What are the strongest cross-aspects?
**Vedic Vimshottari Dasha**
> Run a Vimshottari Mahadasha for someone born 1985-07-22 06:45 in Mumbai (19.07N 72.87E UTC+5.5). Which planet's period are they in right now (May 2026)?
**Transit forecast**
> What major outer-planet transits hit my natal chart on 2027-01-01? Birth: 1990-03-15 14:30 Kyiv (50.45 30.52 UTC+2).
**Tarot reading**
> Pull a 3-card Past-Present-Future spread from the Rider-Waite deck for the question "should I take the new job?". Use seed 42 for reproducibility.
**Human Design**
> What's the Human Design type, strategy and authority for someone born 1990-03-15 14:30 Kyiv (50.45 30.52 UTC+2)? List their defined centers and incarnation cross.
---
## Configuration
| Env var | Default | Description |
|---|---|---|
| `ASTROWAY_API_KEY` | *(required)* | Your API key. Live: `aw_live_...`. Sandbox: `aw_test_...`. |
| `ASTROWAY_BASE_URL` | `https://api.astroway.info/v1` | Override for self-hosted / staging instances. |
---
## How tools are generated
A build-time script reads the canonical endpoint manifest from the production API, classifies each endpoint by input shape (`chart`, `twoChart`, `chartTarget`, `horoscopeSign`, `year`, `date`, `generic`), and emits a typed tool definition. The MCP server then registers every entry against an MCP `Tool` with the appropriate Zod input schema.
When the API ships new endpoints, the next MCP release ships them automatically — no manual tool definitions to keep in sync.
---
## Troubleshooting
**Claude Desktop doesn't show the server.** Check the bottom of the chat input for the MCP indicator (slider icon). Click it to see registered servers and any startup errors. If `astroway` is missing, run the `npx @astroway/mcp` command manually in a terminal — startup errors print to stderr.
**Tools return `Error 401`.** API key is missing, invalid, or revoked. Generate a new one at .
**Tools return `Error 402`.** Out of credits on the free tier. Upgrade at or wait for the monthly reset.
**Tools return `Error 422` with field validation errors.** The LLM passed a body the API didn't accept. Ask Claude to retry with the example body shown in the tool description, or use the sandbox key (`aw_test_...`) to debug without spending credits.
---
## Repository layout
This repo is the **public showcase** for `@astroway/mcp`: README, CHANGELOG, LICENSE, install instructions. The runnable code is the published npm package itself — install it with `npm install @astroway/mcp` or run via `npx @astroway/mcp`.
Source is maintained in the private AstroWay monorepo so the build-time generator can read the canonical endpoint manifest from the API workspace next door. The generated package is open source under MIT and ships every release to npm.
---
## Changelog
See [CHANGELOG.md](CHANGELOG.md).
---
## Links
- 📦 npm:
- 📘 API docs:
- 🔑 Sign up & dashboard:
- 💰 Pricing:
- 🟦 TypeScript SDK: [`@astroway/api`](https://www.npmjs.com/package/@astroway/api)
- 🐍 Python SDK: [`astroway`](https://pypi.org/project/astroway/)
- 🌐 Website:
---
## License
MIT — see [LICENSE](LICENSE).