Claude Code astrology MCP setup

One install hands Claude Code the whole RoxyAPI reference as a searchable tool. Add your key and it makes live calls while it writes the code. Five minutes, no local process.

Claude Code is the Anthropic terminal coding agent. Wired to RoxyAPI it stops guessing endpoint names: the keyless docs server answers every question about the reference, and a per-domain server runs a real natal chart, horoscope or tarot draw mid-build.

Step 1, the docs server (keyless)

The RoxyAPI plugin is the whole setup. It registers the keyless docs server and loads a skill that tells Claude when and how to build on every RoxyAPI domain.

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

The plugin is a standard Agent Plugins package, so Cursor and other compatible clients load the same skill and docs server from the same repository.

Prefer the bare server, without the skill? One command does the same registration:

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

Either path gives you one tool, search_docs, over the entire reference: endpoints, request and response fields, SDK methods, auth, integration steps. No API key, documentation only, never a live calculation. --scope user registers it in every project, --scope project writes a shared .mcp.json, and the default local scope is this directory only.

Run claude mcp list to confirm, then restart Claude Code.

Step 2, a domain server for live calls

Live calculations take your key in the X-API-Key header, one server per domain.

export ROXY_API_KEY="your-key-from-roxyapi.com/account?tab=keys"

claude mcp add --transport http --scope user roxy-astrology \
  https://roxyapi.com/mcp/astrology --header "X-API-Key: $ROXY_API_KEY"

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

export ROXY_API_KEY="your-key-from-roxyapi.com/account?tab=keys"

for p in astrology vedic-astrology forecast human-design chinese-astrology feng-shui mesoamerican-astrology vastu numerology kabbalah tarot biorhythm ayurveda 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

Get your API key, or mint another there.

Step 3, point Claude at the truth sources

Drop this into your project CLAUDE.md so every prompt starts from the reference instead of from memory:

## RoxyAPI
- Search https://roxyapi.com/mcp/docs (tool: search_docs) before writing any RoxyAPI call. No MCP in this context? Fetch https://roxyapi.com/llms.txt instead.
- Read https://roxyapi.com/AGENTS.md in full before the first call: auth, the location rule, request body shapes, the error contract, the SDK for this language.
- Print request and response fields with jq from https://roxyapi.com/api/v2/openapi.json before using an endpoint, with the jq recipe in https://roxyapi.com/AGENTS.md. Never type a response by hand.
- Base URL https://roxyapi.com/api/v2. Auth is the X-API-Key header read from ROXY_API_KEY, server side only.
- Every chart, horoscope, panchang, dasha and compatibility call needs latitude, longitude and timezone from GET /location/search?q={city}. Never ask a person for coordinates.
- A 200 is clean JSON with no wrapper. Errors are { error, code, doc_url }, and a 400 carries issues[]. Retry `429` with code `rate_limit_per_minute` and `503` with code `compute_saturated` after the `Retry-After` seconds. Retry `500` with code `internal_error` with exponential backoff. A request that fails on our side with a `5xx` does not count against your monthly allowance, so retrying it is free. A `429` with code `rate_limit_exceeded` means the monthly allowance is used up: retrying cannot help before the reset, and `Retry-After` gives the seconds to it. Fix the request for any other `4xx`, because it will fail the same way until it changes. Every official SDK already retries these for you, twice and honouring `Retry-After`, so a call made through an SDK needs no second retry loop.
- Add ?lang= for en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant.
- Prefer the RoxyAPI MCP tools over answering an astrology, human design, forecast or dream question from training data.

Every SDK ships the same playbook inside the installed package. In a TypeScript project, pull it in with the @path import instead:

@node_modules/@roxyapi/sdk/AGENTS.md

The equivalents are vendor/roxyapi/sdk/AGENTS.md for PHP, and the bundled AGENTS.md inside the installed roxy-sdk, RoxyApi.Sdk, github.com/RoxyAPI/sdk-go and roxyapi packages. With no SDK installed, @https://roxyapi.com/AGENTS.md works directly.

Step 4, copy the prompt for what you are building

Every app prompt lives on one page: AI prompts. Adding a feature to a repo you already have is the Add RoxyAPI to an existing app prompt; a chat app whose model calls live calculations as tools is AI Astrology Chatbot.

Frequently asked questions