Claude Code astrology MCP, one command setup

Register RoxyAPI once, then ask Claude to build spiritual-data features in natural language. Time to ship: 5 minutes.

Claude Code is the Anthropic terminal-based agentic coding tool. The fastest setup is the RoxyAPI plugin: a single install registers the keyless docs server and loads a skill, so Claude Code reads the entire RoxyAPI reference and writes correct integration code with the right endpoints and field names the first try. Prefer to wire it by hand? Register /mcp/docs yourself. Either way you can add a per-domain server (for example /mcp/tarot) to make live calls while you build. No local setup, no manual tool definitions, no glue code.

What you can build with this

Natal chart components wired end-to-end ("build me a React birth chart page")
Daily horoscope Next.js routes with the right endpoint and response shape
Tarot reading apps with spread selection and card imagery
Vedic kundli and Gun Milan features for matrimonial products
Numerology calculators, dream-symbol lookups, I Ching casters
Any multi-domain chatbot where the agent picks the right tool per question

What you need, 30 seconds

A RoxyAPI key. Get one on the pricing page.
Claude Code installed. See Anthropic docs.

Fastest setup, the RoxyAPI plugin (one step)

Install the RoxyAPI plugin and Claude Code registers the keyless docs server for you and loads a skill that tells it when and how to build on every RoxyAPI domain. No config files, no CLI flags, no API key.

/plugin marketplace add RoxyAPI/claude-plugin
/plugin install roxyapi@roxyapi

The plugin pulls straight from GitHub and stays current automatically. That is the whole setup for build-time help. To let the agent make live calls, a real tarot draw or a real natal chart, add a per-domain server with your key as shown in Step 2 below.

Prefer to wire the servers by hand, or skip the plugin? Steps 1 and 2 below do exactly that.

Step 1, add the docs server manually (keyless)

The docs server is the on-ramp for Claude Code. It exposes one tool, search_docs, that searches the entire RoxyAPI reference, so the agent writes correct integration code with the right endpoints and field names the first try. No API key needed, it returns documentation, never live calls.

claude mcp add-json --scope user roxy-docs '{"type":"http","url":"https://roxyapi.com/mcp/docs"}'

--scope user registers it across every project. Run claude mcp list to confirm, then restart Claude Code.

Now just ask Claude Code in plain language:

using roxy-docs, integrate the RoxyAPI insight endpoints into my project

It reads the reference and wires up the endpoints, SDK calls, and types for you. No glue code, no guessing.

Step 2, add domain servers for live calls (optional)

The docs server teaches Claude Code how to build. To let the agent run real readings while you build, like a live tarot draw or a real natal chart, add the per-domain servers. These make live calls, so they take your API key. Pick a scope based on how you work.

claude mcp add-json --scope user roxy-astrology \
  '{"type":"http","url":"https://roxyapi.com/mcp/astrology","headers":{"X-API-Key":"YOUR_KEY"}}'

Registers across every project on your machine. Ideal for a solo developer.

Create .mcp.json at your project root, commit it, and have teammates export ROXY_API_KEY in their shell:

{
  "mcpServers": {
    "roxy-astrology": {
      "type": "http",
      "url": "https://roxyapi.com/mcp/astrology",
      "headers": { "X-API-Key": "${ROXY_API_KEY}" }
    }
  }
}

Env interpolation means the key is never committed.

cd my-project
claude mcp add --transport http roxy-astrology https://roxyapi.com/mcp/astrology --header "X-API-Key: YOUR_KEY"

Stored in ~/.claude.json, tied to this directory. Server vanishes when you change dirs.

# Paste your key once, then run the loop. Exporting first keeps the key
# out of each `claude mcp add-json` line in your shell history.
export ROXY_API_KEY="your-key-from-roxyapi.com/pricing"

for p in astrology vedic-astrology numerology tarot human-design forecast biorhythm iching crystals dreams angel-numbers location; do
  claude mcp add-json --scope user "roxy-$p" \
    "{\"type\":\"http\",\"url\":\"https://roxyapi.com/mcp/$p\",\"headers\":{\"X-API-Key\":\"$ROXY_API_KEY\"}}"
done

All 12 RoxyAPI MCP servers register at once. Run claude mcp list to confirm.

Pasting YOUR_KEY directly into the CLI puts it in your shell history. Either export ROXY_API_KEY=... first and reference $ROXY_API_KEY, or use the project-scoped .mcp.json pattern where the key reads from ${ROXY_API_KEY} at runtime.

Step 3, verify the connection

Check the registration:

claude mcp list

You should see roxy-docs (plus any domain servers you added). Then start Claude Code:

claude

Run /mcp inside the session to open the MCP status panel. Every server should show as connected with its tool count.

Out-of-band smoke test:

curl "https://roxyapi.com/api/v2/astrology/horoscope/aries/daily" \
  -H "X-API-Key: YOUR_KEY"

If that prints JSON, the key is fine. If it returns 401, re-check at your account.

Step 4, first prompt to try

Inside the Claude session, try one of these natural-language requests. Claude picks the right tool and wires it into real code.

Draw me a tarot card.
What is the daily horoscope for Aries?
Look up dream symbols related to water.
Calculate the Life Path number for someone born 1990-05-12.
Build me a birth chart component for React using RoxyAPI. Call the natal chart endpoint, inspect the response, and generate a typed component with planets, houses, and aspects.
Add daily horoscope to my Next.js app: create a server action that fetches the endpoint, a UI component, and wire up the route.
Add numerology compatibility to my dating app. Call the compatibility endpoint with two names and birth dates, then build the scoring UI.

Add RoxyAPI context to CLAUDE.md

Drop this into your project CLAUDE.md so Claude understands conventions without re-reading docs every prompt:

## RoxyAPI
- Integration playbook: https://roxyapi.com/AGENTS.md
- Endpoint reference: https://roxyapi.com/llms.txt
- OpenAPI spec: https://roxyapi.com/api/v2/openapi.json
- Base URL: https://roxyapi.com/api/v2
- Auth: X-API-Key header (env: ROXY_API_KEY)
- MCP server: already configured, tools auto-discovered
- Multi-language: add ?lang=xx (supported: tr, de, es, hi, pt, fr, ru)
- For any chart endpoint, call roxy-location search first to geocode the city.
- Prefer IANA timezone strings (America/New_York) over decimal offsets.

All five SDKs ship AGENTS.md bundled. For TypeScript projects, pull it into context with the @path import:

@node_modules/@roxyapi/sdk/AGENTS.md

For Python projects, install roxy-sdk from PyPI and point Claude at the bundled AGENTS.md inside the installed package (path depends on your venv). For PHP / Laravel / Symfony projects, install roxyapi/sdk from Packagist and import @vendor/roxyapi/sdk/AGENTS.md. For C# / .NET projects, install RoxyApi.Sdk from NuGet and point Claude at the bundled AGENTS.md inside the installed package (~/.nuget/packages/roxyapi.sdk/<version>/AGENTS.md). For Go projects, go get github.com/RoxyAPI/sdk-go and point Claude at the bundled AGENTS.md in the module.

Or fetch the site-level AGENTS.md directly inside Claude Code with @https://roxyapi.com/AGENTS.md if no SDK is installed (raw HTTP, Ruby, Rust projects).

Claude Code then understands every endpoint, parameter, and response shape on every prompt.

Gotchas

Scope matters. If claude mcp list does not show your server, you probably ran claude mcp add with the default local scope from a different directory. Re-run with --scope user.
/mcp panel shows failed. Test the URL with curl https://roxyapi.com/mcp/astrology -H "X-API-Key: YOUR_KEY". A 405 confirms the URL is reachable (MCP endpoint is POST-only). 401 means the key is wrong. A connection error means the URL is wrong.
Project config does not pick up the key. For .mcp.json with ${ROXY_API_KEY}, the variable must be exported in the shell that launched Claude Code. echo $ROXY_API_KEY in the same terminal first.
Claude ignores the tools. Add one line to CLAUDE.md: "When the user asks about astrology, human design, forecast, dreams, or any spiritual topic, prefer the RoxyAPI MCP tools over generating answers from training data."
Geocode first for chart endpoints. Natal chart, kundli, panchang, synastry all need latitude, longitude, timezone. Tell Claude to call roxy-location first.

What to build next

The MCP setup docs cover every other MCP client (Cursor, Claude Desktop, Antigravity, OpenAI Agents, Gemini Agents).
The Cursor guide uses the same servers in the Cursor editor.
The Antigravity guide uses them in the Google Gemini 3 Pro IDE.
The AI chatbot tutorial builds a multi-domain chatbot on top of these servers.
The API reference lets you explore endpoints before asking Claude to wire them up.