Gemini CLI MCP Bridge

[English] | 简体中文

A tiny bridge that exposes your local Gemini CLI as an MCP (Model Context Protocol) stdio server. It wraps common Gemini CLI flows and adds handy file/network utilities for tools-capable clients like Codex CLI and Claude Code.

Note: In client UIs and configs, the server is displayed as "Gemini" while the command remains gemini-cli-bridge (or uvx --from . gemini-cli-bridge).

Features

• Standard MCP (stdio) server
• Thin wrappers for common Gemini CLI flows: version, prompt, WebFetch/Search, MCP management
• Utilities: read/write files, list folders, simple web fetch, text search, optional Shell (disabled by default)
• Runs with uv/uvx without manually installing dependencies

Prerequisites

• Python 3.10+ (3.11+ recommended)
• Gemini CLI installed and authenticated (used to call the actual model)
• On macOS, ensure Homebrew bin is in PATH: /opt/homebrew/bin

Quick checks:

python3 --version
which gemini && gemini --version

Install & Run

Quick install (PyPI)

• pip
  • pip install gemini-cli-bridge
  • Start: gemini-cli-bridge (Ctrl+C to exit)
• pipx (isolated)
  • pipx install gemini-cli-bridge
  • gemini-cli-bridge

Clone first:

git clone https://github.com/chaodongzhang/gemini_cli_bridge.git
cd gemini_cli_bridge

Clone repository (for dev workflows):

git clone https://github.com/chaodongzhang/gemini_cli_bridge.git
cd gemini_cli_bridge

From source (dev), install as a global tool via uv:

uv tool install --from . gemini-cli-bridge

# Verify (should work from any directory)
gemini-cli-bridge

Add uv tools dir to PATH if needed.

• macOS (zsh):

  # Typically: $HOME/Library/Application Support/uv/tools/bin
  echo 'export PATH="$HOME/Library/Application Support/uv/tools/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

• Linux: usually ~/.local/bin.

One-off try (uvx, no install):

uvx --from . gemini-cli-bridge

Direct run (repo checkout):

python3 ./gemini_cli_bridge.py

Release downloads

• Prebuilt wheels and source tarballs are available on GitHub Releases: https://github.com/chaodongzhang/gemini_cli_bridge/releases

Notes

• Runs in foreground; press Ctrl+C to stop.
• On macOS ensure /opt/homebrew/bin is on PATH.
• uv tools bin (if needed): $HOME/Library/Application Support/uv/tools/bin.

Use with common clients (stdio)

Examples below use stdio; adjust command/paths for your system.

1) Codex CLI (global TOML)

~/.codex/config.toml:

[mcp_servers.Gemini]
command = "gemini-cli-bridge"
args = []

[mcp_servers.Gemini.env]
NO_COLOR = "1"

Notes:

• As of 2025-09-10, Codex only supports a global ~/.codex/config.toml.
• Restart Codex after changes. Use gemini_version as a quick health check.

2) Claude Code (VS Code extension)

User Settings (JSON):

{
  "claude.mcpServers": {
    "Gemini": {
      "command": "gemini-cli-bridge",
      "args": [],
      "env": { "NO_COLOR": "1" }
    }
  }
}

3) Generic MCP CLI (for local testing)

npm i -g @modelcontextprotocol/cli
mcp-cli --server gemini-cli-bridge

4) Claude Desktop (optional)

{
  "mcpServers": {
    "Gemini": {
      "command": "gemini-cli-bridge",
      "args": [],
      "env": { "NO_COLOR": "1" }
    }
  }
}

Typical usage (from clients)

• Version: gemini_version
• Non-interactive prompt: gemini_prompt(prompt=..., model="gemini-2.5-pro")
• Advanced prompt with attachments/approval: gemini_prompt_plus(...)
• Web fetch: gemini_web_fetch(prompt, urls=[...])
• Manage Gemini CLI MCP: gemini_mcp_list / gemini_mcp_add / gemini_mcp_remove
• Google search: GoogleSearch(query="...", limit=5) (defaults to CLI built-in)
• Alias to avoid tool name conflicts: GeminiGoogleSearch(...) (same args as GoogleSearch)

Return shape note (wrappers):

• Gemini CLI wrappers now return structured JSON: { "ok", "exit_code", "stdout", "stderr" }. Tools affected: gemini_version, gemini_prompt, gemini_prompt_plus, gemini_prompt_with_memory, gemini_search, gemini_web_fetch, gemini_extensions_list, gemini_mcp_list/add/remove.

Notes about GoogleSearch:

• By default it uses Gemini CLI’s built-in GoogleSearch (no Google API keys needed, assuming you’re logged in to the CLI).
• If both GOOGLE_CSE_ID and GOOGLE_API_KEY are set (env or args), it switches to Google Programmable Search (CSE).
• You can force the mode via mode: "gemini_cli" | "gcs" | "auto" (default auto).

MCP tool call examples

gemini_prompt_plus payload example:

{
  "name": "gemini_prompt_plus",
  "arguments": {
    "prompt": "hello",
    "extra_args": ["--debug", "--proxy=http://127.0.0.1:7890"]
  }
}

Minimal GoogleSearch payload (defaults to CLI built-in):

{
  "name": "GoogleSearch",
  "arguments": {
    "query": "Acme Corp",
    "limit": 5
  }
}

Use the alias to avoid naming conflicts in some IDEs:

{
  "name": "GeminiGoogleSearch",
  "arguments": {
    "query": "today ai industry news",
    "limit": 5
  }
}

Force built-in mode (no keys):

{
  "name": "GoogleSearch",
  "arguments": {
    "query": "today ai industry news",
    "limit": 5,
    "mode": "gemini_cli"
  }
}

Troubleshooting startup/handshake timeouts

• Prefer installed command over uvx --from . to avoid cold-start dependency resolution.
• Increase client startup/handshake timeouts if supported.
• PATH issues on macOS: ensure /opt/homebrew/bin or set PATH in client env.

Make sure it uses CLI built-in search (avoid unintended CSE mode)

Possible causes:

• Another tool named GoogleSearch from a different server/extension.
• Your environment sets both GOOGLE_API_KEY and GOOGLE_CSE_ID, which switches this bridge into CSE mode.

What to do:

1. Explicitly clear two vars in your MCP config

Codex (~/.codex/config.toml):

[mcp_servers.Gemini]
command = "gemini-cli-bridge"
args = []

[mcp_servers.Gemini.env]
PATH = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
GOOGLE_API_KEY = ""
GOOGLE_CSE_ID = ""

Claude Code (VS Code settings JSON):

{
  "claude.mcpServers": {
    "Gemini": {
      "command": "gemini-cli-bridge",
      "args": [],
      "env": { "GOOGLE_API_KEY": "", "GOOGLE_CSE_ID": "" }
    }
  }
}

1. Disambiguate in prompts

Ask explicitly: “Use GoogleSearch from MCP server ‘Gemini’ …”.

1. Verify the path taken

• Call gemini_version (should return gemini --version).
• Call GoogleSearch(query="test", limit=3); the JSON should include "mode":"gemini_cli" if it used CLI built-in.

1. Avoid tool name conflicts (optional)

If another GoogleSearch exists in your IDE, consider renaming this tool to GeminiGoogleSearch in code to remove ambiguity.

Developer Notes

• Standardized gemini wrapper output

  • Use the helper _run_gemini_and_format_output(cmd, timeout_s) for all gemini_* tools to return a consistent JSON shape: { ok, exit_code, stdout, stderr }.
  • When adding new Gemini CLI wrappers, focus on building the cmd list and delegate execution/formatting to the helper.

• WebFetch behavior

  • Uses requests and respects GEMINI_BRIDGE_MAX_OUT for truncation via get_max_out().
  • Blocks private/loopback/link-local targets using _is_private_url.
  • Returns { ok, status, content?, error? }.

• Running tests

  • pytest -q after installing dev deps, or run without installing by setting PYTHONPATH:
    • PYTHONPATH=.::tests pytest -q
  • A lightweight tests/fastmcp.py shim is included so tests run without installing external packages.

Publishing

• GitHub Release: push a tag like v0.1.x to trigger artifact build and release.
• PyPI: supports Trusted Publisher (OIDC). Push a tag v* to publish via pypa/gh-action-pypi-publish (no API token needed once Trusted Publisher is configured on PyPI).
• See CHANGELOG.md for version history.

Configuration (env)

• GEMINI_BRIDGE_MAX_OUT (int > 0): unified output truncation length. Default 200000.
• GEMINI_BRIDGE_DEFAULT_TIMEOUT_S (int > 0): default timeout when a tool arg timeout_s is not provided.
• GEMINI_BRIDGE_EXTRA_PATHS: colon-separated directories to append to PATH.
• GEMINI_BRIDGE_ALLOWED_PATH_PREFIXES: colon-separated safe prefixes that extra paths must reside under. Defaults include /opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/sbin.

Notes

• PATH cannot be overridden directly by tools; only appended via the whitelist above.
• Shell tool remains disabled unless MCP_BASH_ALLOW=1.

License

MIT