{"_id":"@alvarosw/gemini-cli-mcp","_rev":"5-26521aea7aa1ab00942b6bb9f2391fb8","name":"@alvarosw/gemini-cli-mcp","dist-tags":{"latest":"1.0.5"},"versions":{"1.0.0":{"name":"@alvarosw/gemini-cli-mcp","version":"1.0.0","keywords":["mcp","gemini","gemini-cli","claude-code","agent","api-key-rotation"],"license":"MIT","_id":"@alvarosw/gemini-cli-mcp@1.0.0","maintainers":[{"name":"alvarosw","email":"alvarossmiguel@gmail.com"}],"bin":{"gemini-cli-mcp":"src/index.js"},"dist":{"shasum":"fbfb55a4111714def50db8940f4e6b56b890fd8d","tarball":"https://registry.npmjs.org/@alvarosw/gemini-cli-mcp/-/gemini-cli-mcp-1.0.0.tgz","fileCount":8,"integrity":"sha512-r5ME+cXIFitSX/ldw0H7WJHPT4n3G1mdR4x7zPGW7Dye0YV1wUPX72afPhXnsuExkBCuKwOt5qNpzUUjo3jQFQ==","signatures":[{"sig":"MEQCIC7DYGR81k2+fn8G8J2Q1H6IqYx88fTb3pIfWQj9HsXzAiBzOdF/YCtyaOF0zDvoeVrTi6pGKAzyul1Rr7T7FHBOYA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":24193},"main":"src/index.js","type":"module","engines":{"node":">=18"},"gitHead":"e18f77e7d11aad2916e7922c7a94690e2a978a93","scripts":{"start":"node src/index.js"},"_npmUser":{"name":"alvarosw","email":"alvarossmiguel@gmail.com"},"_npmVersion":"10.9.2","description":"A lightweight MCP server for Gemini CLI with transparent API-key rotation on rate limits.","directories":{},"_nodeVersion":"22.17.1","dependencies":{"@modelcontextprotocol/sdk":"^1.17.5"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/gemini-cli-mcp_1.0.0_1788051507791_0.6055956470890143","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@alvarosw/gemini-cli-mcp","version":"1.0.1","keywords":["mcp","gemini","gemini-cli","claude-code","agent","api-key-rotation"],"license":"MIT","_id":"@alvarosw/gemini-cli-mcp@1.0.1","maintainers":[{"name":"alvarosw","email":"alvarossmiguel@gmail.com"}],"bin":{"gemini-cli-mcp":"src/index.js"},"dist":{"shasum":"c0dab0429bf607c5e04bdb90e67035367e17e9dc","tarball":"https://registry.npmjs.org/@alvarosw/gemini-cli-mcp/-/gemini-cli-mcp-1.0.1.tgz","fileCount":8,"integrity":"sha512-qHMgzP8FFOtHzBUI0Yqrl7g9QYkRr+tFHdcsysyqQGDOUAwjtkDXBptNiM5GTNmQXfUmvu6T6hi+XNHJsOpcsg==","signatures":[{"sig":"MEUCIE0sRM7eilPqcLram5NxoL46h9LCYq9YQt8wuBDXM4aIAiEA86hATKSBPu2+ExCpOMpidtFbgfzuA7AFE+/ij7Y61Dk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":24239},"main":"src/index.js","type":"module","engines":{"node":">=18"},"gitHead":"1f32d36c1b3737bf27de4bcd3c039b7f216d9842","scripts":{"start":"node src/index.js"},"_npmUser":{"name":"alvarosw","email":"alvarossmiguel@gmail.com"},"_npmVersion":"10.9.2","description":"A lightweight MCP server for Gemini CLI with transparent API-key rotation on rate limits.","directories":{},"_nodeVersion":"22.17.1","dependencies":{"@modelcontextprotocol/sdk":"^1.17.5"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/gemini-cli-mcp_1.0.1_1788052215708_0.29619012410677814","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@alvarosw/gemini-cli-mcp","version":"1.0.2","keywords":["mcp","gemini","gemini-cli","claude-code","agent","api-key-rotation"],"license":"MIT","_id":"@alvarosw/gemini-cli-mcp@1.0.2","maintainers":[{"name":"alvarosw","email":"alvarossmiguel@gmail.com"}],"bin":{"gemini-cli-mcp":"src/index.js"},"dist":{"shasum":"74a011a98a7e2630c8f659683326eadf9581953d","tarball":"https://registry.npmjs.org/@alvarosw/gemini-cli-mcp/-/gemini-cli-mcp-1.0.2.tgz","fileCount":8,"integrity":"sha512-zrnF4b1HjBCMErk+kTpGfqhgmopuW9GVZhHSlEi3V9shQ10g1GK8iFEVcRN3XLUkJGLxD1pzPg9POYpIHO9VLw==","signatures":[{"sig":"MEQCIDZdyP+IL0NcE3RG6JUkjz//2w/qFHg6a7CuYKLl+9TbAiAonXw/4JyoxyYn3019TRD/a6Rs0bbJ7VR6LH1WK41bcA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":24493},"main":"src/index.js","type":"module","engines":{"node":">=18"},"gitHead":"8856e6d0ae020c14b46a86a28e7bbfeda784c89e","scripts":{"start":"node src/index.js"},"_npmUser":{"name":"alvarosw","email":"alvarossmiguel@gmail.com"},"_npmVersion":"10.9.2","description":"A lightweight MCP server for Gemini CLI with transparent API-key rotation on rate limits.","directories":{},"_nodeVersion":"22.17.1","dependencies":{"@modelcontextprotocol/sdk":"^1.17.5"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/gemini-cli-mcp_1.0.2_1788063777694_0.10434641331766903","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@alvarosw/gemini-cli-mcp","version":"1.0.3","keywords":["mcp","gemini","gemini-cli","claude-code","agent","api-key-rotation"],"license":"MIT","_id":"@alvarosw/gemini-cli-mcp@1.0.3","maintainers":[{"name":"alvarosw","email":"alvarossmiguel@gmail.com"}],"bin":{"gemini-cli-mcp":"src/index.js"},"dist":{"shasum":"16cb3d4602eef454bc695f33dcff3ea220d17694","tarball":"https://registry.npmjs.org/@alvarosw/gemini-cli-mcp/-/gemini-cli-mcp-1.0.3.tgz","fileCount":8,"integrity":"sha512-s/vA88Eina6KVoQvEGw9JFXlc0mowbt6Fn56HHyMsNzZ+5ZQMTo9aRSAri+tOgcL8/eI23jmL+6Y8mkUr7BRuQ==","signatures":[{"sig":"MEUCIBJCIdVfRJrk1DmkKYUK5K8J7/kfVSa/OsUXDTe1We8uAiEAlkIcz9ND9F7/Jc5OmYw88Q3M3NcrqL5va+zm4vyvRz8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":24805},"main":"src/index.js","type":"module","engines":{"node":">=18"},"gitHead":"5cf1536aed83233a520c1c55c15260f35cf235f8","scripts":{"start":"node src/index.js"},"_npmUser":{"name":"alvarosw","email":"alvarossmiguel@gmail.com"},"_npmVersion":"10.9.2","description":"A lightweight MCP server for Gemini CLI with transparent API-key rotation on rate limits.","directories":{},"_nodeVersion":"22.17.1","dependencies":{"@modelcontextprotocol/sdk":"^1.17.5"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/gemini-cli-mcp_1.0.3_1788064106780_0.7202912186775308","host":"s3://npm-registry-packages-npm-production"}},"1.0.5":{"name":"@alvarosw/gemini-cli-mcp","version":"1.0.5","description":"A lightweight MCP server for Gemini CLI with transparent API-key rotation on rate limits.","type":"module","main":"src/index.js","bin":{"gemini-cli-mcp":"src/index.js"},"scripts":{"start":"node src/index.js"},"keywords":["mcp","gemini","gemini-cli","claude-code","agent","api-key-rotation"],"license":"MIT","engines":{"node":">=18"},"dependencies":{"@modelcontextprotocol/sdk":"^1.17.5"},"_id":"@alvarosw/gemini-cli-mcp@1.0.5","gitHead":"09fa61763d8c8ed8731079e4dc2be095fc902feb","_nodeVersion":"22.17.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-+VcjAn4ThyeSgBBaSkMBVxO3bWYBcIRt2YVpAjvcch/rMhmYRxsL6E41gbDhF7a2m9ixb4QI9a96N9MxV7gjTg==","shasum":"f8edfdafdb08a6078a50a0eb7dbcb41b332a646b","tarball":"https://registry.npmjs.org/@alvarosw/gemini-cli-mcp/-/gemini-cli-mcp-1.0.5.tgz","fileCount":8,"unpackedSize":24931,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIH2wTO7xQmpB+LApJgwsOj5MSxcvFbx2c9c6F7Q9xSz7AiAY36w67H4csEYyC18nFcmuG6Vm0CnkMUOQ3CZL0Flnnw=="}]},"_npmUser":{"name":"alvarosw","email":"alvarossmiguel@gmail.com"},"directories":{},"maintainers":[{"name":"alvarosw","email":"alvarossmiguel@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/gemini-cli-mcp_1.0.5_1788064464655_0.6087809952850123"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-30T00:58:27.660Z","modified":"2026-08-30T04:34:24.953Z","1.0.0":"2026-08-30T00:58:27.937Z","1.0.1":"2026-08-30T01:10:15.887Z","1.0.2":"2026-08-30T04:22:57.825Z","1.0.3":"2026-08-30T04:28:26.935Z","1.0.5":"2026-08-30T04:34:24.818Z"},"license":"MIT","keywords":["mcp","gemini","gemini-cli","claude-code","agent","api-key-rotation"],"description":"A lightweight MCP server for Gemini CLI with transparent API-key rotation on rate limits.","maintainers":[{"name":"alvarosw","email":"alvarossmiguel@gmail.com"}],"readme":"# Gemini CLI MCP\n\nA lightweight MCP server that exposes the official **Gemini CLI** to MCP clients such as Claude Code, while adding transparent API-key rotation for `429` rate-limit responses.\n\n## Why this exists\n\nGemini CLI already provides headless execution with `--prompt` and structured JSON output. This project wraps that CLI instead of reimplementing its agent runtime.\n\nThe extra feature is the local API gateway:\n\n```text\nMCP client\n   |\n   v\nGemini CLI process\n   |\n   | GOOGLE_GEMINI_BASE_URL\n   v\nLocal API gateway\n   |\n   +---- key A ----> Gemini API\n   |\n   +---- key B ----> Gemini API\n   |\n   +---- key C ----> Gemini API\n```\n\nWhen Gemini API returns `429`, the gateway marks the current key as temporarily unavailable, retries the same HTTP request with the next available key, and only returns an error if the retry budget is exhausted.\n\nThis means the **same Gemini CLI process and session can continue**. The MCP does not restart the agent from the beginning of the job just because an intermediate API request was rate-limited.\n\n> API keys must be keys you own or are authorized to use. Respect Google's quotas, terms, and rate limits.\n\n## Requirements\n\n- Node.js 18+\n- Gemini CLI installed and available in `PATH` (as `gemini` on macOS/Linux or `gemini.cmd` on Windows)\n- Gemini API key(s) from Google AI Studio when using API-key authentication\n\nGemini CLI documents `GEMINI_API_KEY` as its API-key authentication environment variable.\n\nOn Windows, the MCP automatically detects and uses `gemini.cmd`. To use a different command, set the `GEMINI_CMD` environment variable.\n\nGemini CLI headless mode supports `--prompt` / `-p` and structured output formats including `json` and `stream-json`.\n\n## Install with npm\n\n```bash\nnpm install -g @alvarosw/gemini-cli-mcp\n```\n\n## Configure API keys\n\nSingle key:\n\n```bash\nexport GEMINI_API_KEY=\"your-key\"\n```\n\nMultiple keys:\n\n```bash\nexport GEMINI_API_KEYS=\"key-one,key-two,key-three\"\n```\n\nOn PowerShell:\n\n```powershell\n$env:GEMINI_API_KEYS=\"key-one,key-two,key-three\"\n```\n\n`GEMINI_API_KEYS` accepts comma, semicolon, or newline-separated values.\n\n## Claude Code\n\n```bash\nclaude mcp add gemini \\\n  --env GEMINI_CLI_TRUST_WORKSPACE=true \\\n  --scope user --transport stdio \\\n  -- npx @alvarosw/gemini-cli-mcp\n```\n\nWith multiple keys:\n\n```bash\nclaude mcp add gemini \\\n  --env GEMINI_API_KEYS=\"key-1,key-2,key-3\" \\\n  --env GEMINI_CLI_TRUST_WORKSPACE=true \\\n  --scope user --transport stdio \\\n  -- npx @alvarosw/gemini-cli-mcp\n```\n\nOn macOS/Linux:\n\n```bash\nclaude mcp add gemini \\\n  --env GEMINI_API_KEYS=\"key-one,key-two,key-three\" \\\n  --env GEMINI_CLI_TRUST_WORKSPACE=true \\\n  --scope user --transport stdio \\\n  -- npx @alvarosw/gemini-cli-mcp\n```\n\nPrefer configuring the keys in your shell environment or a secret manager rather than committing them to a project.\n\n## Other MCP clients\n\nGeneric MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"gemini\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@alvarosw/gemini-cli-mcp\"],\n      \"env\": {\n        \"GEMINI_API_KEYS\": \"key-one,key-two,key-three\"\n      }\n    }\n  }\n}\n```\n\nThis pattern works with MCP hosts that support local stdio servers and environment variables.\n\n## Tools\n\n### `gemini_run`\n\nRun Gemini CLI in headless mode with common options:\n\n- prompt\n- model\n- output format\n- approval mode\n- sandbox / yolo\n- session resume\n- included directories\n- allowed MCP servers\n- extensions\n- experimental integrations\n- arbitrary extra CLI arguments\n\nExample payload:\n\n```json\n{\n  \"prompt\": \"Review the authentication flow in this repository and propose fixes.\",\n  \"cwd\": \"/path/to/project\",\n  \"model\": \"auto\",\n  \"outputFormat\": \"json\",\n  \"approvalMode\": \"plan\"\n}\n```\n\n### `gemini_raw`\n\nPass arbitrary arguments directly to the Gemini CLI when `gemini_run` does not cover a new CLI capability.\n\n```json\n{\n  \"args\": [\"--version\"]\n}\n```\n\n### `gemini_usage`\n\nShows the local key-pool state: number of keys, cooldowns, failures, and last HTTP status.\n\nThis is **not** a provider-side quota report.\n\n### `gemini_version`\n\nReturns the installed Gemini CLI version.\n\n### `gemini_help`\n\nReturns the current Gemini CLI help output.\n\n### `gemini_models`\n\nRuns a non-interactive model-selection query. For exact current CLI behavior, use `gemini_raw` with the desired model-related flags.\n\n### `gemini_cli_info`\n\nShows the active CLI command, proxy address, and redacted key-pool status.\n\n## API-key failover\n\nThe proxy rotates keys only for upstream `429` responses.\n\nFor example:\n\n```text\nRequest #1 -> key A -> 200\nRequest #2 -> key A -> 429\n               |\n               +-> key B -> 200\nRequest #3 -> key B -> 200\n```\n\nKeys that return `429` are placed on cooldown using the upstream `Retry-After` value when available, otherwise `GEMINI_KEY_COOLDOWN_MS` (default: 60 seconds).\n\n### Configuration\n\n| Variable | Default | Description |\n| --- | --- | --- |\n| `GEMINI_API_KEYS` | — | Comma/semicolon/newline-separated API keys |\n| `GEMINI_API_KEY` | — | Fallback single API key |\n| `GEMINI_KEY_COOLDOWN_MS` | `60000` | Cooldown when `Retry-After` is unavailable |\n| `GEMINI_MAX_KEY_RETRIES` | `key count - 1` | Maximum fallback attempts per request |\n| `GEMINI_PROXY_HOST` | `127.0.0.1` | Local proxy bind host |\n| `GEMINI_PROXY_PORT` | `0` | Local proxy port; `0` selects a free port |\n| `GEMINI_TARGET_URL` | Google Gemini API | Upstream Gemini API base URL |\n| `GEMINI_CMD` | `gemini` on macOS/Linux; `gemini.cmd` on Windows | Gemini CLI executable |\n\n## Important limitation\n\nThis gateway solves the important case where the CLI process makes multiple model requests and one intermediate request receives `429`: the **failed HTTP request is retried in place**, so the surrounding Gemini CLI session is not restarted.\n\nIt does not make an already-started streaming response resumable after bytes have been delivered. Rate-limit responses normally arrive as HTTP status responses before the response body, so the gateway can retry those requests cleanly.\n\n## Security\n\nThe API gateway is bound to `127.0.0.1` by default and is intended for local use. Do not expose it publicly.\n\nAPI keys are injected into the upstream request at the gateway and are never returned by MCP tools. `gemini_usage` and `gemini_cli_info` redact key values.\n\n## Development\n\n```bash\nnpm install\nnpm start\n```\n\nRun syntax checks:\n\n```bash\nnode --check src/index.js\nnode --check src/tools.js\nnode --check src/gemini.js\nnode --check src/key-pool.js\nnode --check src/proxy.js\n```\n\n## References\n\n- [Gemini CLI documentation](https://geminicli.com/docs/)\n- [Gemini CLI headless mode](https://geminicli.com/docs/cli/headless/)\n- [Gemini CLI authentication](https://geminicli.com/docs/get-started/authentication/)\n","readmeFilename":"README.md"}