{"id":50359230,"url":"https://github.com/astroway/astroway-mcp","last_synced_at":"2026-05-30T00:03:07.708Z","repository":{"id":356186852,"uuid":"1231359678","full_name":"astroway/astroway-mcp","owner":"astroway","description":"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.","archived":false,"fork":false,"pushed_at":"2026-05-27T12:18:05.000Z","size":95,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-27T14:15:04.610Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"https://api.astroway.info/docs/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/astroway.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-06T22:17:47.000Z","updated_at":"2026-05-21T12:11:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/astroway/astroway-mcp","commit_stats":null,"previous_names":["astroway/astroway-mcp"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/astroway/astroway-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astroway%2Fastroway-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astroway%2Fastroway-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astroway%2Fastroway-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astroway%2Fastroway-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/astroway","download_url":"https://codeload.github.com/astroway/astroway-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astroway%2Fastroway-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33675019,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2026-05-30T00:03:06.958Z","updated_at":"2026-05-30T00:03:07.701Z","avatar_url":"https://github.com/astroway.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @astroway/mcp\n\n\u003e 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.\n\n[![npm version](https://img.shields.io/npm/v/@astroway/mcp.svg?style=flat\u0026color=blue)](https://www.npmjs.com/package/@astroway/mcp)\n[![npm downloads](https://img.shields.io/npm/dm/@astroway/mcp.svg?style=flat)](https://www.npmjs.com/package/@astroway/mcp)\n[![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![MCP](https://img.shields.io/badge/MCP-1.0-purple.svg)](https://modelcontextprotocol.io)\n\nNatal 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.\n\nTools 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.\n\n---\n\n## Install\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"astroway\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@astroway/mcp\"],\n      \"env\": {\n        \"ASTROWAY_API_KEY\": \"aw_live_...\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop. The `astroway` server will appear in the MCP indicator at the bottom of the chat input.\n\n### Cursor\n\nAdd to `~/.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"astroway\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@astroway/mcp\"],\n      \"env\": { \"ASTROWAY_API_KEY\": \"aw_live_...\" }\n    }\n  }\n}\n```\n\n### Other MCP clients\n\nRun as a stdio server:\n\n```bash\nASTROWAY_API_KEY=aw_live_... npx @astroway/mcp\n```\n\n---\n\n## Get an API key\n\nSign up at \u003chttps://api.astroway.info/dashboard/sign-up\u003e — **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/)).\n\nFor local testing without a paid plan, use a sandbox key (`aw_test_...`) which returns deterministic responses for free.\n\n---\n\n## What you get\n\nTool 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).\n\n| Category | Examples |\n|---|---|\n| **Core** | natal chart, planet positions, draconic, harmonics |\n| **Comparisons** | synastry, composite, davison, cross-system compatibility |\n| **Prognostics** | transits, secondary progressions, solar/lunar return, transit calendar |\n| **Specialized Charts** | heliocentric, sidereal, eclipse search |\n| **Aspects \u0026 Points** | aspects table, antiscia, midpoints, Arabic parts, fixed stars |\n| **Calendar \u0026 Cycles** | retrograde periods, ingresses, lunar phases, planetary hours |\n| **Dignities \u0026 Receptions** | essential dignities, almuten, hyleg, dispositors |\n| **Horary** | horary chart, moon void-of-course, via combusta |\n| **Human Design** | full chart, transits, penta, dream rave, hologenetic profile |\n| **Astro-Geography** | astrocartography, local space, relocation chart |\n| **Vedic** | 16 Vargas, Panchang, Shadbala, 4 Dasha systems × 5 levels (Vimshottari / Yogini / Ashtottari / Kalachakra), Yogas, Doshas, Compatibility, Muhurat |\n| **Tarot** | Rider-Waite-Smith, Marseille, Lenormand decks; spreads + card lookups |\n| **Numerology** | Pythagorean, Chaldean, Kabbalistic, Vedic, Destiny Matrix |\n| **Esoteric** | I Ching, sabian symbols, fortune dice, color \u0026 gemstone correspondences |\n| **Reference** | signs, planets, houses, aspects, nakshatras, Hellenistic Lots |\n| **AI Interpretations** | natal, synastry, transits — Ukrainian/English |\n| **Horoscope** | daily, weekly, monthly, compatibility (zodiac sign-based) |\n\n---\n\n## Example prompts\n\nAfter connecting the server, try these in Claude Desktop:\n\n**Natal chart**\n\u003e 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.\n\n**Synastry**\n\u003e 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?\n\n**Vedic Vimshottari Dasha**\n\u003e 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)?\n\n**Transit forecast**\n\u003e 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).\n\n**Tarot reading**\n\u003e 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.\n\n**Human Design**\n\u003e 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.\n\n---\n\n## Configuration\n\n| Env var | Default | Description |\n|---|---|---|\n| `ASTROWAY_API_KEY` | *(required)* | Your API key. Live: `aw_live_...`. Sandbox: `aw_test_...`. |\n| `ASTROWAY_BASE_URL` | `https://api.astroway.info/v1` | Override for self-hosted / staging instances. |\n\n---\n\n## How tools are generated\n\nA 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.\n\nWhen the API ships new endpoints, the next MCP release ships them automatically — no manual tool definitions to keep in sync.\n\n---\n\n## Troubleshooting\n\n**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.\n\n**Tools return `Error 401`.** API key is missing, invalid, or revoked. Generate a new one at \u003chttps://api.astroway.info/dashboard/keys\u003e.\n\n**Tools return `Error 402`.** Out of credits on the free tier. Upgrade at \u003chttps://api.astroway.info/pricing/\u003e or wait for the monthly reset.\n\n**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.\n\n---\n\n## Repository layout\n\nThis 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`.\n\nSource 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.\n\n---\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md).\n\n---\n\n## Links\n\n- 📦 npm: \u003chttps://www.npmjs.com/package/@astroway/mcp\u003e\n- 📘 API docs: \u003chttps://api.astroway.info/docs/api/\u003e\n- 🔑 Sign up \u0026 dashboard: \u003chttps://api.astroway.info/dashboard/\u003e\n- 💰 Pricing: \u003chttps://api.astroway.info/pricing/\u003e\n- 🟦 TypeScript SDK: [`@astroway/api`](https://www.npmjs.com/package/@astroway/api)\n- 🐍 Python SDK: [`astroway`](https://pypi.org/project/astroway/)\n- 🌐 Website: \u003chttps://astroway.info\u003e\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastroway%2Fastroway-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fastroway%2Fastroway-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastroway%2Fastroway-mcp/lists"}