MCP — connecting Claude / Cursor

@astroway/mcp is a Model Context Protocol server that exposes all 705 AstroWay endpoints as tools to an AI agent. One npm package, native integration with Claude Desktop, Cursor, and any MCP-compatible client.

Source: github.com/astroway/astroway-mcp · npm: npmjs.com/package/@astroway/mcp

How it works

The tool list is generated at build time from the live OpenAPI spec (api.astroway.info/v1/openapi.json). Every package release picks up new endpoints automatically — no manual maintenance.

Each endpoint becomes a tool:

• tools/list returns a description and input schema (with a request body example)
• tools/call POSTs to https://api.astroway.info/v1/<path> using your ASTROWAY_API_KEY
• The response is returned to the agent as structured JSON

Each release also ships SLSA provenance (Sigstore-attested) — a guarantee that the npm package was built from the exact commit in the public source repo.

Install

Claude Desktop (macOS)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Restart Claude Desktop. A 🛠️ indicator with the loaded tool count appears under the chat input.

Cursor

Add to ~/.cursor/mcp.json:

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

Cline / Continue / Windsurf / Copilot / VS Code MCP

The same npx @astroway/mcp command works in every MCP-compatible client. Identical config — only the path to the config file differs:

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

Client	Config path
Cline (VS Code)	.cline/mcp.json in workspace root
Continue	~/.continue/config.json (under mcpServers)
Windsurf	~/.codeium/windsurf/mcp_config.json
GitHub Copilot Chat (VS Code)	enable preview → mcp.json in workspace
VS Code MCP extension	~/.vscode/mcp.json

Other MCP clients

Run as a stdio server:

ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp

Tip

Get a key at api.astroway.info/dashboard/sign-up. Free tier — 10,000 credits/month, no card required.

Privacy — from v1.0.0+

This MCP server does not phone home. There is no telemetry, no analytics, no usage reporting — and no opt-in / opt-out toggle. 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/<version> (Node/<node-version>)
• X-Astroway-Channel: mcp

Neither carries a session ID, machine fingerprint, or anything personal. They mirror standard User-Agent semantics — every CLI tool already sends similar information.

Subset registration — from v1.0.0+

If you only use part of the catalogue, register a subset and keep your LLM context window lean:

{
  "env": {
    "ASTROWAY_API_KEY": "aw_live_...",
    "ASTROWAY_TOOL_GROUPS": "western,vedic,relational",   // only these prefixes
    "ASTROWAY_READONLY": "1"                               // skip ai/horoscope/reports (LLM-backed, costs credits)
  }
}

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.

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.

Stability commitment — from v1.0.0+

• Catalogue is frozen for the duration of a session. The 624 tools, 12 prompts, and 14 resources are baked into the published npm package — they don’t change at runtime. If your client caches tools/list after the first call, it stays correct for the whole connection.
• Tool identifiers are stable inside a major version. A name shipped under astroway_<group>_<tool> won’t be renamed or removed within v1.x without a deprecation note in CHANGELOG.md and a one-minor parallel-availability window.
• Tool input shape is stable inside a minor version. Tightening (regex, range, enum) ships in patches; adding a required field requires a minor bump.
• Refresh the catalogue by reinstalling. npm i -g @astroway/mcp@latest (or the npx -y @astroway/mcp form already in your client config) pulls the current set on the next start.

Example prompts

After connecting the server, ask the AI:

Natal chart

Calculate my natal chart — born 1990-03-15 14:30 in Kyiv. Describe the Sun, Moon, Ascendant and find any tight aspects.

Claude calls the chart tool with your params, gets structured JSON, and describes the chart in natural language.

Transits

Which significant outer-planet transits hit my natal chart during 2027?

Claude makes two tool calls: first transits (current snapshot), then transit-calendar (range). Interprets the trends.

Vedic Mahadasha

Run Vimshottari Mahadasha for someone born 1985-07-22 06:45 in Mumbai. Which period are they in right now?

Through the vedic/dashas/vimshottari/maha tool — exact UTC timestamp for the current period.

Synastry

Compare two charts: A — 1988-06-10 09:15 London, B — 1991-11-22 22:40 Berlin. What are the strongest cross-aspects?

synastry tool with two chart blocks + compatibility score interpretation.

Tarot

Pull 3 Rider-Waite-Smith cards: Past — Present — Future. Question: “should I take the new job?”. Seed = 42.

tarot/rider-waite/spread with a fixed seed for reproducibility.

Listing all tools

After connecting, ask Claude:

List all astroway tools.

Or from the command line:

ASTROWAY_API_KEY=aw_test_smoke npx @astroway/mcp 2>&1 | head -1
# (starts the stdio server; tool-list calls come from the MCP client over the protocol)

Configuration

Variable	Default	Description	Since
ASTROWAY_API_KEY	(required)	Live: aw_live_.... Sandbox: aw_test_....	0.1.0
ASTROWAY_BASE_URL	https://api.astroway.info/v1	Override for self-hosted / staging environments.	0.1.0
ASTROWAY_TOOL_GROUPS	(all groups)	Comma-separated prefixes to limit catalogue (western,vedic,relational).	1.0.0
ASTROWAY_READONLY	0	1 skips LLM-backed groups (ai, horoscope, reports).	1.0.0
LOG_LEVEL	error	silent/error/warn/info/debug — stderr log verbosity.	0.8.0
LOG_FILE	(not written)	File path to mirror stderr logs to.	0.8.0
MCP_FLAT_TOOLS	0	1 returns pre-v0.9 flat names (chart instead of astroway_western_chart). Legacy.	0.9.0

Why MCP, not direct integration

A generic LLM (without grounding) will say “some time in July Saturn will trine your Jupiter” — no exact date, ±15 days drift. The MCP agent does tool_use POST /v1/transits and returns a UTC timestamp down to the second, on real Swiss Ephemeris.

The win isn’t from the LLM — it’s the guarantee that the math is real, not made up.

Package distribution

• mcp.so listing: mcp.so/server/astroway-mcp/astroway
• mcpservers.org: awaiting approval (as of May 2026)
• awesome-mcp-servers (punkpeye): PR #5972

Links

• 📦 npm: npmjs.com/package/@astroway/mcp
• 📘 API docs: /docs/api/
• 🔑 Sign up: /dashboard/sign-up
• 💰 Pricing: /pricing/
• 🌐 Public repo (MIT): github.com/astroway/astroway-mcp