gemini-mcp-bridge

gemini-mcp-bridge

## Deprecated and unmaintained Google is retiring Gemini CLI on June 18, 2026 in favor of Antigravity CLI. After that date, Gemini CLI stops serving requests for Google AI Pro, Ultra, and free tier accounts (Gemini Code Assist for individuals). Enterprise customers on paid Gemini Code Assist Standard/Enterprise licenses retain access. Because this bridge wraps Gemini CLI as a subprocess, it stops working for individual users on the same date. This repository is archived and the npm package is deprecated. No further releases are planned. Migration options: - Antigravity CLI is Google's successor, written in Go, with Agent Skills, Hooks, Subagents, and plugins. Note: it is not open source. - For other terminal agents, see the sibling bridges: claude-mcp-bridge, codex-mcp-bridge. Existing installs continue to function until June 18, 2026. The historical README follows.

---

      

MCP server that wraps Gemini CLI as a subprocess, exposing its capabilities as Model Context Protocol tools.

Works with any MCP client: Claude Code, Codex CLI, Cursor, Windsurf, VS Code, or any tool that speaks MCP.

Do you need this?

If you're in a terminal agent (Claude Code, Codex CLI) with shell access, call Gemini CLI directly:

# File context query
gemini -p "Explain how this auth flow works" -- @src/auth.ts @src/session.ts

# Quick question
gemini -p "Is this approach sound for handling retries?"

# Web search
gemini -p --yolo "What's the latest stable Node.js LTS?"

Tips: --yolo is needed for agentic file access in headless mode (without it, tool calls block). Use -m gemini-2.5-pro to skip the CLI's internal model routing (~1-2s). Cold start is ~16s per invocation. For code review, see Code review with this CLI below.

Use this MCP bridge instead when:

• Your client has no shell access (Cursor, Windsurf, Claude Desktop, VS Code)
• You need structured output with JSON Schema validation (Gemini CLI has no custom schema support)
• You need concurrency management (max 3 parallel spawns, FIFO queue, optional pacing/jitter between CLI starts)
• You need partial response capture on timeout (NDJSON streaming) and automatic model fallback on quota errors
• You need response length controls (maxResponseLength parameter)
• You need oversized query/search responses paginated safely instead of getting truncated by MCP client limits (structured is intentionally not chunked, preserves machine-consumable JSON)
• You want subprocess isolation: env allowlist, path sandboxing, no shell escape

Quick Start

npx gemini-mcp-bridge

Prerequisites

• Gemini CLI installed (npm i -g @google/gemini-cli)
• Authenticated (gemini auth login)

Claude Code

claude mcp add gemini -s user -- npx -y gemini-mcp-bridge

Codex CLI

Add to ~/.codex/config.json: ``json { "mcpServers": { "gemini": { "command": "npx", "args": ["-y", "gemini-mcp-bridge"] } } } ``

Cursor / Windsurf / VS Code

Add to your MCP settings: ``json { "gemini": { "command": "npx", "args": ["-y", "gemini-mcp-bridge"] } } ``

Tools

| Tool | Description | |------|-------------| | query | Agentic prompt with optional file context. Gemini runs inside your repo with read/grep/glob tools. Supports text and images. | | search | Google Search grounded query. Gemini searches the web and synthesizes an answer with source URLs. | | structured | JSON Schema validated output via Ajv. Data extraction, classification, or any task needing machine-parseable output. | | ping | Health check. Verifies CLI is installed and authenticated, reports versions and capabilities. | | fetch-chunk | Retrieve later segments from a chunked query or search response using its cacheKey. |

query

Send a prompt with optional file paths as hints. Gemini reads the files itself and can explore surrounding code for context. Text queries run under --approval-mode plan (read-only agentic). Image queries use --yolo for native pixel access.

Key parameters: prompt (required), files (text or images), model, workingDirectory, timeout (default 120s, max 1800s), changeMode (see below).

Change mode: set changeMode: true to ask Gemini to emit structured FILE: <path>:<start>-<end> / ===OLD=== / ===NEW=== edit blocks instead of prose. The raw response stays in response (chunked normally); parsed edits are returned on _meta.edits as a machine-applicable array and are never chunked. A pre/post-spawn git snapshot detects any file writes Gemini might attempt, if writes are found, _meta.appliedWrites is set to true and edits is omitted so callers can't re-apply half-applied state. Text-only for v1; requires a git workingDirectory. Plan mode refuses to emit edit blocks (verified on CLI 0.38.0), so change mode runs in default agentic mode with the snapshot guardrail as the safety net.

search

Google Search grounded query. Spawns Gemini CLI in agentic mode with google_web_search, then synthesizes an answer with source URLs.

Key parameters: query (required), model, workingDirectory, timeout.

Large query and search responses are automatically chunked when they exceed the bridge threshold. The first chunk includes a cacheKey and chunk count in _meta and the response footer. Use fetch-chunk with that cacheKey and a 1-based chunkIndex to retrieve later segments within the 10-minute in-memory cache window. structured responses are intentionally not chunked (preserves machine-consumable JSON output).

structured

Generate JSON conforming to a provided schema. Schema is embedded in the prompt, response validated with Ajv. Returns isError: true with validation details on failure.

Key parameters: prompt (required), schema (required, JSON string), files, model, workingDirectory, timeout.

ping

No parameters. Returns CLI version, auth status, and server info.

All tools attach execution metadata (_meta) with durationMs, model, and partial (timeout indicator). See DESIGN.md for details.

Code review with this CLI

The review and assess tools were removed in v0.7.0 (see ADR-001). The gemini ecosystem already ships several review surfaces, listed here in priority order:

1. Official gemini-cli-extensions/code-review extension (repo). Adds /code-review and /pr-code-review slash commands to the CLI.
2. Skills (/skills, .gemini/skills/code-reviewer/SKILL.md). Project- or user-scoped review prompts, invokable as slash commands.
3. Subagents (.gemini/agents/, ~/.gemini/agents/). Specialized reviewer personas the CLI can delegate to.
4. Gemini Code Assist GitHub app. Inline review on pull requests.
5. Direct gemini -p with hardened isolation flags. Pipe the diff via stdin (using $(git diff ...) as positional args expands the diff into shell tokens):

   git diff origin/main...HEAD | gemini --approval-mode plan \
     -e "" \
     --allowed-mcp-server-names "" \
     -p "Review the diff on stdin for bugs, missing tests, and unhandled errors"

--approval-mode plan is read-only agentic. -e "" disables loaded extensions for this run. --allowed-mcp-server-names "" blocks bundled MCP servers. Default text output is preferred over --output-format json for human-readable review notes.

1. Third-party MCP servers if you specifically need an MCP-shaped review tool (e.g. nicobailon/gemini-code-review-mcp).

Configuration

| Variable | Default | Description | |----------|---------|-------------| | GEMINI_DEFAULT_MODEL | (CLI default) | Default model for all tools | | GEMINI_FALLBACK_MODEL | gemini-2.5-flash | Fallback on quota/rate-limit errors (none to disable) | | GEMINI_CLI_PATH | gemini | Path to CLI binary | | GEMINI_MAX_CONCURRENT | 3 | Max concurrent subprocess spawns | | GEMINI_MIN_INVOCATION_GAP_MS | 5000 | Minimum gap between Gemini CLI start times | | GEMINI_SPAWN_JITTER_MAX_MS | 200 | Random extra delay before spawn to avoid deterministic timing |

Prompt templates for the search, structured, and query change-mode tools live in prompts/. Editable when running from a local clone; bundled when running via npx.

Choosing a Gemini MCP server

| You need... | Consider | |-------------|----------| | Schema-validated structured output, concurrency management, response chunking | This bridge | | Shell command generation, Google Workspace integration | @tuannvm/gemini-mcp-server | | Lightweight large-context codebase analysis | gemini-mcp-tool | | No CLI dependency (API-only, broadest feature set) | @rlabs-inc/gemini-mcp | | Simple API wrapper with broad client support | mcp-server-gemini |

Performance

Each invocation spawns a fresh CLI process with ~15-20s cold start (large dependency tree, sync auth checks). No daemon mode yet (tracking; PR in progress).

| Scenario | Typical time | |----------|-------------| | Minimal query | 17-25s | | File-context query (small repo) | 30-60s | | Web search + synthesis | 35-60s | | Structured output (small schema) | 25-45s |

Setting GEMINI_DEFAULT_MODEL avoids the CLI's internal model routing step (~1-2s savings per call).

Bridge family

Three MCP servers, same architecture, different underlying CLIs. Each wraps a terminal agent as a subprocess and exposes it as MCP tools. Pick the one that matches your model provider, or run multiple for cross-model workflows.

| | gemini-mcp-bridge | claude-mcp-bridge | codex-mcp-bridge | |---|---|---|---| | CLI | Gemini CLI | Claude Code | Codex CLI | | Provider | Google | Anthropic | OpenAI | | Tools | query, structured, search, fetch-chunk, ping | query, structured, search, ping, listSessions | codex, query, structured, search, ping, listSessions | | Code review | Use the gemini ecosystem: code-review extension, skills, subagents, Code Assist, or gemini -p | Use Claude Code built-ins (/review, /security-review, /ultrareview) or claude -p | Use codex review --base <ref> (native CLI subcommand) | | Structured output | Ajv validation | Native --json-schema | Ajv validation | | Session resume | Not supported | Native --resume | Session IDs with multi-turn | | Budget caps | Not supported | Native --max-budget-usd | Not supported | | Effort control | Not supported | --effort low/medium/high/max | reasoningEffort (low/medium/high) | | Cold start | ~16s | ~1-2s | <100ms (inference dominates) | | Auth | gemini auth login | claude login (subscription) or ANTHROPIC_API_KEY | OPENAI_API_KEY | | Cost | Free tier available | Subscription (included) or API credits | Pay-per-token | | Concurrency | 3 (configurable) | 3 (configurable) | 3 (configurable) | | Model fallback | Auto-retry with fallback model | Auto-retry with fallback model | Auto-retry with fallback model |

All three share: subprocess env isolation, path sandboxing, FIFO concurrency queue, MCP tool annotations, _meta response metadata, progress heartbeats. The codex and claude bridges also perform output redaction (secret stripping).

Development

npm install
npm run build        # Compile TypeScript
npm run dev          # Watch mode
npm test             # Run tests
npm run lint         # ESLint
npm run typecheck    # tsc --noEmit

Further reading

• DESIGN.md - Architecture, output streaming, concurrency, response metadata, prompt templates
• SECURITY.md - Environment isolation, path sandboxing, agentic mode caveats, resource limits
• CHANGELOG.md - Release history

License

MIT