gemini-mcp-bridge

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:

# Agentic review (Gemini explores the repo, reads files, follows imports)
cd /path/to/repo && gemini -p --yolo "Review the changes on this branch vs main"

# Review specific files
gemini -p "Review this code for bugs and security issues" -- @src/file.ts @src/other.ts

# Pipe a diff
git diff origin/main...HEAD | gemini -p "Review this diff"

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

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.

Use this MCP bridge instead when:

• Your client has no shell access (Cursor, Windsurf, Claude Desktop, VS Code)
• You want to know the cost before you pay it, assess classifies a diff in <2s (no spawn) and recommends a review depth with an estimated wall time
• You need graduated review depth rather than all-or-nothing: scan (diff-only, ~40s), focused (reads changed files, 1-3min), deep (full agentic, up to 30min) with per-depth auto-scaled timeouts
• 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), automatic model fallback on quota errors for most tools, and structured capacity failures for deep review
• You need response length controls (maxResponseLength parameter)
• You need oversized query/review/search responses paginated safely instead of getting truncated by MCP client limits
• 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:

{
  "mcpServers": {
    "gemini": {
      "command": "npx",
      "args": ["-y", "gemini-mcp-bridge"]
    }
  }
}

Cursor / Windsurf / VS Code

Add to your MCP settings:

{
  "gemini": {
    "command": "npx",
    "args": ["-y", "gemini-mcp-bridge"]
  }
}

Tools

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.

assess

Runs git diff --numstat and --name-only locally and returns diff stats, changed file list, complexity (trivial/moderate/complex), change kind (empty / code / mixed / non-code / generated), guidance, and suggested review depths with estimated wall-clock time. No CLI spawn, no model call, returns in under 2 seconds.

Key parameters: uncommitted (default true), base, workingDirectory.

review

Three depth tiers, selectable via the depth parameter. Use the assess tool first for a recommendation.

• scan: diff-only, single-pass, no repo exploration. Constant 180s timeout. Good for sanity checks and small diffs.
• focused: pre-computed diff + Gemini reads changed files for surrounding context. Plan mode, no shell. Timeout 120s + 15s * files (cap 300s; 240s fallback). Good for light-to-moderate reviews.
• deep (default): full agentic exploration with --yolo. Gemini runs git diff itself, follows imports, checks tests, reads project instruction files (AGENTS.md, CLAUDE.md, GEMINI.md, etc.). Timeout 240s + 45s * files (cap 1800s; 600s fallback). On capacity failures such as 429/503, deep review returns structured failure metadata instead of retrying or silently downgrading. Deepest.

The legacy quick boolean is deprecated but still honoured: quick: true → depth: "scan", quick: false → depth: "deep". depth wins when both are set.

Key parameters: uncommitted (default true), base, focus, depth, workingDirectory, timeout, maxResponseLength.

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, review, 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

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). Review may also attach capacityFailure; assess includes diffKind, guidance, and suggestions. See DESIGN.md for details.

Configuration

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

Choosing a Gemini MCP server

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).

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.

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