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

... View full README on GitHub