# Gemini CLI, connect Roxy as an MCP server

> Register Roxy once with the gemini mcp command, then build spiritual-data features in natural language. Remote MCP, no local server to run. Time to ship: 5 minutes.

[Gemini CLI](https://github.com/google-gemini/gemini-cli) is Google's open-source terminal AI agent. It connects to MCP servers through your `settings.json`, so it can call real tools while it writes code. RoxyAPI runs as a Remote MCP server over streamable HTTP, so Gemini reads the entire Roxy reference and writes correct integration code with the right endpoints and field names the first try. Start with the keyless docs server, then add a per-domain server (for example `/mcp/tarot`) to make live calls while you build. No local process, 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 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 Life Path calculators, dream-symbol lookups, I Ching hexagram casters
- Any multi-domain companion where Gemini picks the right tool per question, a transit, a tarot pull, or a nakshatra, across all 12 domains under one key

## What you need, 30 seconds

1. A Roxy API key. Get one on the [pricing page](/pricing).
2. Gemini CLI installed. Follow the [Gemini CLI setup](https://github.com/google-gemini/gemini-cli).

## Step 1, add the docs server (keyless)

The docs server is the on-ramp for Gemini. It searches the entire Roxy 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.

The `gemini mcp add` command writes to your `settings.json`. 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
```

Start Gemini and run `/mcp` to confirm the server is connected. Now just ask 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 Gemini 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 in the `X-API-Key` header.


### One domain

```bash
gemini mcp add --transport http --scope user roxy-astrology \
  https://roxyapi.com/mcp/astrology --header "X-API-Key: YOUR_KEY"
```

### settings.json

Streamable HTTP servers use the `httpUrl` field. 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": "YOUR_KEY" }
    }
  }
}
```

### Add all 12 domains

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

All 12 Roxy MCP servers register at once. Run `gemini mcp list` to confirm.


**Warning: Gemini CLI does not expand environment variables inside MCP `headers`, so your key is written into `settings.json` in plaintext whichever path you use. Keep `settings.json` out of version control, and prefer user scope (`~/.gemini/settings.json`) over a committed project `.gemini/settings.json`.**

## Step 3, verify the connection

List the configured servers:

```bash
gemini mcp list
```

You should see `roxy-docs` plus any domain servers you added, each marked Connected. Inside a Gemini session, run `/mcp` to see every server with its tool count.

Out-of-band smoke test:

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

If that prints JSON, the key is fine. If it returns 401, re-check at [your account](/account).

## Step 4, first prompt to try

Inside Gemini, try one of these natural-language requests. It 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. Call the natal chart endpoint, inspect the response, and generate a typed component with planets, houses, and aspects.
- Add numerology compatibility to my dating app. Call the compatibility endpoint with two names and birth dates, then build the scoring UI.

## Add Roxy context to GEMINI.md

Gemini reads `GEMINI.md` from your project (and `~/.gemini/GEMINI.md` globally) as standing instructions on every prompt. Drop this block into `GEMINI.md` so it understands Roxy conventions without re-reading docs every prompt:

```markdown
## Roxy API
- 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](/docs/sdk "RoxyAPI TypeScript, Python, PHP, C#, and Go SDKs") ship an `AGENTS.md` playbook bundled. To have Gemini read that file directly, add its name to the context file list in `settings.json`:

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

Then point Gemini at the site-level <a href="/AGENTS.md" target="_blank" rel="noopener" title="AGENTS.md execution playbook for AI coding agents - tight language-agnostic guide">AGENTS.md</a> at `https://roxyapi.com/AGENTS.md`, the tight, language-agnostic execution playbook with Rule 0, common task body shapes, and the field gotcha table. Gemini then understands every endpoint, parameter, and response shape on every prompt.

## Gotchas

- **`httpUrl`, not `url`.** In `settings.json`, streamable HTTP servers use `httpUrl`. The `url` field is for SSE, and `command` is for local stdio.
- **Keys land in settings.json.** Gemini CLI does not interpolate environment variables inside `headers`, so the key is stored in plaintext. Keep `settings.json` out of git and prefer user scope.
- **X-API-Key, not Authorization Bearer.** Roxy uses a custom header. Pass `--header "X-API-Key: YOUR_KEY"` or set it under `headers`.
- **Use `/mcp` to check status.** Inside a session, `/mcp` lists every server, its connection state, and its tools. `gemini mcp list` does the same from the shell.
- **Geocode first for chart endpoints.** Natal chart, kundli, panchang, and synastry all need `latitude`, `longitude`, and `timezone`. Tell Gemini to call `roxy-location` first.

## Frequently asked questions


### Does Gemini CLI support remote MCP servers?
Yes. Gemini CLI connects to streamable HTTP (Remote) MCP servers using the `httpUrl` field in `settings.json`, alongside SSE (`url`) and stdio (`command`). RoxyAPI runs Remote MCP over streamable HTTP, so there is no local process to install or keep running.

### How do I add a RoxyAPI key to a Gemini CLI MCP server?
RoxyAPI authenticates with the `X-API-Key` header. Pass `--header "X-API-Key: YOUR_KEY"` on `gemini mcp add`, or set a `headers` object in `settings.json`. Gemini CLI does not expand environment variables in headers, so the key is stored in `settings.json`. Keep that file out of version control.

### Can Gemini CLI read the RoxyAPI AGENTS.md?
Yes. Gemini reads `GEMINI.md` by default, and you can add `AGENTS.md` to the context file list with `"context": { "fileName": ["AGENTS.md", "GEMINI.md"] }` in `settings.json`, so the RoxyAPI SDK playbook is loaded as standing context.

### Is RoxyAPI free to try with Gemini CLI?
The keyless docs MCP server at https://roxyapi.com/mcp/docs needs no key and returns documentation so Gemini writes correct code before you pay. Live calls across all 12 domains need an API key from the [pricing page](/pricing), billed at a flat rate where 1 request equals 1 quota unit, every domain included.

## What to build next

- The [MCP setup docs](/docs/mcp) cover every other MCP client (Cursor, Claude Code, Codex, OpenAI Agents, Gemini Agents).
- The [Codex guide](/docs/guides/codex) and [Claude Code guide](/docs/guides/claude-code) use the same servers in other terminal agents.
- The [AI chatbot tutorial](/docs/tutorials/ai-chatbot) builds a multi-domain chatbot on top of these servers.
- The [API reference](/api-reference) lets you explore endpoints before asking Gemini to wire them up.