gemini-cli-mcp

中文文档

A secure MCP server that wraps Google's Gemini CLI. It lets Claude Code (or any MCP client) call Gemini models using your local OAuth session — no API key required.

Highlights

• Secure — spawn(shell:false) on Unix; controlled shell:true + arg escaping on Windows. No command injection.
• Cross-platform — macOS, Linux, Windows. Auto-resolves .cmd wrappers and forces UTF-8.
• Activity-based timeout — idle timer resets on each output chunk. Long thinking won't be killed; stuck 429 retries will.
• Low token overhead — replaces Gemini's ~8 800-token default system prompt with a minimal one (~50 tokens).
• Clean output — internally uses stream-json and parses structured responses. No stdout noise pollution.
• 2 tools only — gemini_query + gemini_info. Minimal context-window footprint for the host AI.

Prerequisites

1. Node.js >= 18 — Download
2. Google Gemini CLI — installed globally and logged in:

npm install -g @google/gemini-cli
gemini   # run once — complete the Google OAuth login in your browser

3. Verify it works before using this MCP server:

gemini -p "say hello" -o text
# Should print a response. If you see auth errors, re-run `gemini` to log in.

Install

NPM (recommended)

npm install -g @xjoker/gemini-cli-mcp

# Register with Claude Code
claude mcp add gemini-cli -s user -- gemini-cli-mcp

From source

git clone https://github.com/xjoker/gemini-cli-mcp.git
cd gemini-cli-mcp
npm install && npm run build

claude mcp add gemini-cli -s user -- node $(pwd)/dist/index.js

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gemini-cli": {
      "command": "gemini-cli-mcp"
    }
  }
}

Upgrade

npm update -g @xjoker/gemini-cli-mcp

Tools

gemini_query

Send a prompt to Gemini.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | prompt | string | Yes | Prompt text. Use @file.ts to include local files. | | model | string | No | Model name or alias (default: gemini-2.5-flash) | | sandbox | boolean | No | Run in sandboxed environment | | yolo | boolean | No | Auto-approve all tool actions | | approval_mode | enum | No | default / auto_edit / yolo / plan | | include_stats | boolean | No | Append token usage stats | | include_directories | string[] | No | Extra workspace directories | | cwd | string | No | Working directory for @file references |

gemini_info

Diagnostics and metadata — most actions cost zero API calls.

| Action | Description | API call? | |--------|-------------|-----------| | ping | Test CLI connectivity | No | | version | Get CLI version | No | | list_models | Show available models and aliases | No | | list_sessions | List past Gemini sessions | No | | list_extensions | List installed Gemini extensions | No |

Models

| Model | Tier | Description | |-------|------|-------------| | gemini-2.5-pro | stable | High reasoning & creativity | | gemini-2.5-flash | stable | Fast, balanced (default) | | gemini-2.5-flash-lite | stable | Fastest, lightest | | gemini-3-pro-preview | preview | Gemini 3 Pro | | gemini-3-flash-preview | preview | Gemini 3 Flash | | gemini-3.1-pro-preview | preview | Gemini 3.1 Pro (rolling out) | | gemini-3.1-flash-lite-preview | preview | Gemini 3.1 Flash Lite |

Aliases: auto, pro, flash, flash-lite

Free tier quota: 60 RPM / 1 000 requests per day.

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | GEMINI_MODEL | gemini-2.5-flash | Default model | | GEMINI_STARTUP_TIMEOUT | 15000 | Phase 1 idle timeout (ms) — CLI startup and initial response | | GEMINI_TIMEOUT | 120000 | Phase 2 idle timeout (ms) — thinking, resets on each output chunk | | GEMINI_MAX_RESPONSE | 100000 | Max response chars before truncation | | GEMINI_BIN | gemini | Path to Gemini CLI binary | | GEMINI_SYSTEM_MD | (bundled minimal) | Path to custom system prompt, or "default" for Gemini built-in |

Security

| Platform | Strategy | |----------|----------| | Unix | child_process.spawn() with shell: false — user input never reaches a shell | | Windows | shell: true (required for .cmd) with % -> %% and ! -> ^^! escaping |

• Zero usage of exec() / execSync() / template-string commands.
• Verify: grep -rn "exec(" src/ returns nothing.

License

MIT