Gemini CLI astrology MCP setup

One command hands Gemini CLI the whole RoxyAPI reference as a searchable tool. Add your key and it runs live calculations while it writes the code. Five minutes, no local process.

Gemini CLI is the Google open-source terminal agent, and it reads MCP servers from settings.json. RoxyAPI runs as a Remote MCP server over Streamable HTTP, so the keyless docs server answers every question about endpoints, fields and SDK methods, and a per-domain server pulls a real natal chart, horoscope or tarot spread mid-build.

Step 1, the docs server (keyless)

gemini mcp add writes the entry for you. Register the docs server at user scope so it works in every project:

bash

gemini mcp add --transport http --scope user roxy-docs https://roxyapi.com/mcp/docs

That is 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.

Start Gemini, run /mcp to confirm the server is connected, then ask in plain language:

Code

Using roxy-docs, find the natal chart endpoint and show me how to call it with the TypeScript SDK.

Step 2, a domain server for live calls

Live calculations take your key in the X-API-Key header, one server per domain. Gemini CLI resolves $VAR and ${VAR} inside settings.json string values when it loads the file, so keep the key in your environment and write only the placeholder.

bash

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

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

Single quotes matter: they stop your shell expanding the variable, so the placeholder lands in settings.json rather than the key itself.

Streamable HTTP servers use httpUrl. Edit ~/.gemini/settings.json (user) or .gemini/settings.json (project):

json

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

bash

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
  gemini mcp add --transport http --scope user "roxy-$p" \
    "https://roxyapi.com/mcp/$p" --header 'X-API-Key: $ROXY_API_KEY'
done

Every RoxyAPI server registers at once, 258+ tools in total. Start with the two or three domains you are actually building on: every connected tool is a definition in front of the model on every turn. Run gemini mcp list to confirm.

Get your API key, or mint another there.

Step 3, point Gemini at the truth sources

Gemini reads GEMINI.md from your project, and ~/.gemini/GEMINI.md globally, as standing instructions on every prompt. Drop this in:

markdown

## 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. Generate types from that spec, never 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.

On a repo shared with other agents, keep the block in AGENTS.md instead and add that filename to the context list so Gemini loads it too. Every SDK ships the same playbook inside the installed package:

json

{
  "context": { "fileName": ["AGENTS.md", "GEMINI.md"] }
}

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 whole app from a blank repository is Astrology Birth Chart App or the domain prompt beside it.

Frequently asked questions

httpUrl or url for the RoxyAPI server?

httpUrl. In settings.json, Streamable HTTP servers use httpUrl, url is the older SSE transport, and command is a local stdio process. RoxyAPI is Streamable HTTP, so a url entry connects to nothing.

How do I keep the RoxyAPI key out of settings.json?

Write "X-API-Key": "$ROXY_API_KEY" and export the variable. Gemini CLI resolves $VAR_NAME and ${VAR_NAME} in settings.json string values when the settings load, so the file carries the placeholder and never the key. Adding the server from the shell needs single quotes around the header, otherwise your shell expands the variable and the real key is written to disk.

gemini mcp add put the server in the wrong file. Why?

The default scope is project, which writes .gemini/settings.json inside the repository. Pass --scope user to write ~/.gemini/settings.json instead and get the server in every project.

How do I make Gemini read the RoxyAPI AGENTS.md?

Add the filename to the context list in settings.json with "context": { "fileName": ["AGENTS.md", "GEMINI.md"] }. Gemini then loads both as standing context, hierarchically, so the file nearest your working directory supplements the ones above it.

Is RoxyAPI free to try with Gemini CLI?

The docs server at https://roxyapi.com/mcp/docs needs no key and returns documentation, so Gemini writes correct code from the first prompt. Live calculations across the domains need your API key, billed flat, 1 request to 1 quota unit, every domain included.