gemini-bridge
Gemini Bridge
AIコーディングアシスタントが公式CLIを通じてGoogleのGemini AIと対話できるようにする、軽量なMCP(Model Context Protocol)サーバーです。Claude Code、Cursor、VS Code、およびその他のMCP互換クライアントで動作します。シンプルさ、信頼性、そしてシームレスな統合を重視して設計されています。
✨ 特徴
Gemini CLI直接統合: 公式Gemini CLIを使用するためAPIコストはゼロ
3つのMCPツール: 基本的なクエリ、ファイル分析、Web検索機能
ステートレスな動作: セッション、キャッシュ、複雑な状態管理は一切なし
本番環境対応: 設定可能な60秒のタイムアウトを備えた堅牢なエラーハンドリング
最小限の依存関係:
mcp>=1.0.0と Gemini CLI のみが必要簡単なデプロイ: uvx と従来の pip インストールの両方をサポート
ユニバーサルなMCP互換性: MCP互換のあらゆるAIコーディングアシスタントで動作
モダンなPython: pathlib とモダンな型ヒントを使用 (Python 3.10+)
Related MCP server: Globalping
🚀 クイックスタート
前提条件
Gemini CLIのインストール:
npm install -g @google/gemini-cliGeminiの認証:
gemini auth loginインストールの確認:
gemini --version
インストール
🎯 推奨: PyPIインストール
# Install from PyPI
pip install gemini-bridge
# Add to Claude Code with uvx (recommended)
claude mcp add gemini-bridge -s user -- uvx gemini-bridge代替手段: ソースからインストール
# Clone the repository
git clone https://github.com/shelakh/gemini-bridge.git
cd gemini-bridge
# Build and install locally
uvx --from build pyproject-build
pip install dist/*.whl
# Add to Claude Code
claude mcp add gemini-bridge -s user -- uvx gemini-bridge開発用インストール
# Clone and install in development mode
git clone https://github.com/shelakh/gemini-bridge.git
cd gemini-bridge
pip install -e .
# Add to Claude Code (development)
claude mcp add gemini-bridge-dev -s user -- python -m src🌐 マルチクライアントサポート
Gemini BridgeはMCP互換のあらゆるAIコーディングアシスタントで動作します - 同じサーバーが、異なる設定方法を通じて複数のクライアントをサポートします。
サポートされているMCPクライアント
Claude Code ✅ (デフォルト)
Cursor ✅
VS Code ✅
Windsurf ✅
Cline ✅
Void ✅
Cherry Studio ✅
Augment ✅
Roo Code ✅
Zencoder ✅
MCP互換のあらゆるクライアント ✅
設定例
# Recommended installation
claude mcp add gemini-bridge -s user -- uvx gemini-bridge
# Development installation
claude mcp add gemini-bridge-dev -s user -- python -m srcグローバル設定 (~/.cursor/mcp.json):
{
"mcpServers": {
"gemini-bridge": {
"command": "uvx",
"args": ["gemini-bridge"],
"env": {}
}
}
}プロジェクト固有設定 (.cursor/mcp.json をプロジェクト内に配置):
{
"mcpServers": {
"gemini-bridge": {
"command": "uvx",
"args": ["gemini-bridge"],
"env": {}
}
}
}移動先: Settings → Cursor Settings → MCP → Add new global MCP server
設定 (.vscode/mcp.json をワークスペース内に配置):
{
"servers": {
"gemini-bridge": {
"type": "stdio",
"command": "uvx",
"args": ["gemini-bridge"]
}
}
}代替手段: 拡張機能経由
拡張機能ビューを開く (Ctrl+Shift+X)
MCP拡張機能を検索
コマンド
uvx gemini-bridgeでカスタムサーバーを追加
WindsurfのMCP設定に追加してください:
{
"mcpServers": {
"gemini-bridge": {
"command": "uvx",
"args": ["gemini-bridge"],
"env": {}
}
}
}Clineを開き、上部ナビゲーションの MCP Servers をクリック
Installed タブ → Advanced MCP Settings を選択
cline_mcp_settings.jsonに追加:
{
"mcpServers": {
"gemini-bridge": {
"command": "uvx",
"args": ["gemini-bridge"],
"env": {}
}
}
}移動先: Settings → MCP → Add MCP Server
{
"mcpServers": {
"gemini-bridge": {
"command": "uvx",
"args": ["gemini-bridge"],
"env": {}
}
}
}Settings → MCP Servers → Add Server に移動
サーバーの詳細を入力:
Name:
gemini-bridgeType:
STDIOCommand:
uvxArguments:
["gemini-bridge"]
設定を保存
UIを使用する場合:
ハンバーガーメニュー → Settings → Tools をクリック
+ Add MCP ボタンをクリック
コマンドを入力:
uvx gemini-bridge名前: Gemini Bridge
手動設定:
"augment.advanced": {
"mcpServers": [
{
"name": "gemini-bridge",
"command": "uvx",
"args": ["gemini-bridge"],
"env": {}
}
]
}Settings → MCP Servers → Edit Global Config に移動
mcp_settings.jsonに追加:
{
"mcpServers": {
"gemini-bridge": {
"command": "uvx",
"args": ["gemini-bridge"],
"env": {}
}
}
}Zencoderメニュー (...) → Tools → Add Custom MCP に移動
設定を追加:
{
"command": "uvx",
"args": ["gemini-bridge"],
"env": {}
}Install ボタンを押す
pipベースのインストールの場合:
{
"command": "gemini-bridge",
"args": [],
"env": {}
}開発/ローカルテストの場合:
{
"command": "python",
"args": ["-m", "src"],
"env": {},
"cwd": "/path/to/gemini-bridge"
}npmスタイルのインストールの場合 (必要な場合):
{
"command": "npx",
"args": ["gemini-bridge"],
"env": {}
}ユニバーサルな使用方法
どのクライアントで設定しても、同じ2つのツールを使用できます:
一般的な質問: "What authentication patterns are used in this codebase?"
特定のファイルの分析: "Review these auth files for security issues"
サーバーの実装は同一です - クライアントの設定のみが異なります!
⚙️ 設定
タイムアウト設定
デフォルトでは、Gemini BridgeはすべてのCLI操作に対して60秒のタイムアウトを使用します。より長いクエリ(大きなファイル、複雑な分析)の場合は、GEMINI_BRIDGE_TIMEOUT 環境変数を使用してカスタムタイムアウトを設定できます。
設定例:
# Add with custom timeout (120 seconds)
claude mcp add gemini-bridge -s user --env GEMINI_BRIDGE_TIMEOUT=120 -- uvx gemini-bridge{
"mcpServers": {
"gemini-bridge": {
"command": "uvx",
"args": ["gemini-bridge"],
"env": {
"GEMINI_BRIDGE_TIMEOUT": "120"
}
}
}
}タイムアウトのオプション:
デフォルト: 60秒 (設定されていない場合)
範囲: 正の整数 (秒)
呼び出しごとの上書き: ツールに
timeout_secondsを指定して一時的に延長可能推奨: 大きなファイルの分析には120〜300秒
無効な値: 警告とともに60秒にフォールバック
🛠️ 利用可能なツール
consult_gemini
単純なクエリのための直接CLIブリッジ。
パラメータ:
query(string): Geminiに送信する質問やプロンプトdirectory(string): クエリの作業ディレクトリmodel(string, オプション): 使用するモデル - "flash", "pro", "flash-lite", "2.5-lite", "3-pro", "3-flash", "3.1-pro", "3.1-flash-lite", または "auto" (デフォルト: "flash")timeout_seconds(int, オプション): このリクエストの実行タイムアウトを上書き
例:
consult_gemini(
query="Find authentication patterns in this codebase",
directory="/path/to/project",
model="flash"
)consult_gemini_with_files
詳細な分析のためにファイルを添付できるCLIブリッジ。
パラメータ:
query(string): Geminiに送信する質問やプロンプトdirectory(string): クエリの作業ディレクトリfiles(list): ディレクトリからの相対ファイルパスのリストmodel(string, オプション): 使用するモデル - "flash", "pro", "flash-lite", "2.5-lite", "3-pro", "3-flash", "3.1-pro", "3.1-flash-lite", または "auto" (デフォルト: "flash")timeout_seconds(int, オプション): このリクエストの実行タイムアウトを上書きmode(string, オプション): ファイル内容をストリーミングする"inline"(デフォルト) または、Gemini CLI自身に@path参照を解決させる"at_command"
例:
consult_gemini_with_files(
query="Analyze these auth files and suggest improvements",
directory="/path/to/project",
files=["src/auth.py", "src/models.py"],
model="pro",
timeout_seconds=180
)ヒント: 大きなツリーをスキャンする場合は、Gemini CLIがファイルグロブと切り捨てをネイティブに処理できるように mode="at_command" に切り替えてください。
web_search
Web検索のコンテキストを含めてGeminiに質問します。モデルが必要と判断した場合にGemini CLIの自動Web検索を使用します。ベストエフォート型の機能であり、すべてのクエリで保証されるわけではありません。
パラメータ:
query(string): Webで検索するクエリや質問directory(string): コマンド実行の作業ディレクトリmodel(string, オプション): 使用するモデル - "flash", "pro", "flash-lite", "2.5-lite", "3-pro", "3-flash", "3.1-pro", "3.1-flash-lite", または "auto" (デフォルト: "flash")timeout_seconds(int, オプション): このリクエストの実行タイムアウトを上書き
例:
web_search(
query="latest Python version and new features",
model="flash"
)📋 使用例
基本的なコード分析
# Simple research query
consult_gemini(
query="What authentication patterns are used in this project?",
directory="/Users/dev/my-project"
)詳細なファイルレビュー
# Analyze specific files
consult_gemini_with_files(
query="Review these files and suggest security improvements",
directory="/Users/dev/my-project",
files=["src/auth.py", "src/middleware.py"],
model="pro"
)複数ファイルの分析
# Compare multiple implementation files
consult_gemini_with_files(
query="Compare these database implementations and recommend the best approach",
directory="/Users/dev/my-project",
files=["src/db/postgres.py", "src/db/sqlite.py", "src/db/redis.py"],
mode="at_command"
)Web検索
# Get current information from the web
web_search(
query="latest Python version and new features in 3.13",
model="flash"
)大きなファイルの保護措置
インライン転送は、ハングを防ぐためにファイルあたり約256 KB、リクエストあたり約512 KBに制限されています。
サイズ超過のファイルは、MCPレスポンス内で警告とともに先頭/末尾の断片に切り捨てられます。
環境変数 (
GEMINI_BRIDGE_MAX_INLINE_TOTAL_BYTESなど) で上限を調整するか、より大きなペイロードにはmode="at_command"を優先してください。
🏗️ アーキテクチャ
コア設計
CLIファースト:
geminiコマンドへの直接サブプロセス呼び出しステートレス: 各ツール呼び出しは独立しており、セッション状態は保持されません
適応型タイムアウト: デフォルトは60秒ですが、リクエストごとまたは環境変数で上書き可能
添付ファイルのガードレール: インラインモードは軽量な制限を強制し、
@モードはGemini CLIツールに委譲しますシンプルなエラーハンドリング: フェイルファストのアプローチによる明確なエラーメッセージ
プロジェクト構造
gemini-bridge/
├── src/
│ ├── __init__.py # Entry point
│ ├── __main__.py # Module execution entry point
│ └── mcp_server.py # Main MCP server implementation
├── .github/ # GitHub templates and workflows
├── pyproject.toml # Python package configuration
├── README.md # This file
├── CONTRIBUTING.md # Contribution guidelines
├── CODE_OF_CONDUCT.md # Community standards
├── SECURITY.md # Security policies
├── CHANGELOG.md # Version history
└── LICENSE # MIT license🔧 開発
ローカルテスト
# Install in development mode
pip install -e .
# Run directly
python -m src
# Test CLI availability
gemini --versionClaude Codeとの統合
MCPプロトコルを通じて適切に設定されると、サーバーは自動的にClaude Codeと統合されます。
🔍 トラブルシューティング
CLIが利用できない
# Install Gemini CLI
npm install -g @google/gemini-cli
# Authenticate
gemini auth login
# Test
gemini --version接続の問題
Gemini CLIが適切に認証されているか確認してください
ネットワーク接続を確認してください
Claude CodeのMCP設定が正しいか確認してください
geminiコマンドがPATHに含まれていることを確認してください
一般的なエラーメッセージ
"CLI not available": Gemini CLIがインストールされていないか、PATHにありません
"Authentication required":
gemini auth loginを実行してください"Timeout after 60 seconds": クエリに時間がかかりすぎました。小さなパーツに分割してみてください
🤝 貢献
コミュニティからの貢献を歓迎します!開始方法の詳細については、Contributing Guidelines をお読みください。
クイック貢献ガイド
リポジトリをフォークする
フィーチャーブランチを作成する
変更を加える
必要に応じてテストを追加する
プルリクエストを送信する
📄 ライセンス
このプロジェクトはMITライセンスの下でライセンスされています - 詳細については LICENSE ファイルを参照してください。
🔄 バージョン履歴
詳細なバージョン履歴については CHANGELOG.md を参照してください。
🆘 サポート
Issues: バグ報告や機能リクエストは GitHub Issues まで
Discussions: コミュニティの議論に参加してください
Documentation: 追加のドキュメントは
docs/ディレクトリに作成できます
焦点: 公式CLIを通じてClaude CodeとGemini AIを接続する、シンプルで信頼性の高いブリッジ。
Available Tools
3 toolsconsult_geminiA
Send a query directly to the Gemini CLI.
Args:
query: Prompt text forwarded verbatim to the CLI.
directory: Working directory used for command execution.
model: Optional model alias (``flash``, ``pro``) or full Gemini model id.
timeout_seconds: Optional per-call timeout override in seconds.
Returns:
Gemini's response text or an explanatory error string.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | ||
| query | Yes | ||
| directory | Yes | ||
| timeout_seconds | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses that the query is 'forwarded verbatim to the CLI', explains optional parameters (model, timeout), and describes the return value as 'Gemini's response text or an explanatory error string'. This provides sufficient behavioral context for a query tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with Args/Returns sections and no extraneous content. It is concise but includes necessary parameter details. Minor tightening could improve it, but overall effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 params, 2 required) and presence of an output schema (implied by return description), the description covers the key behavioral aspects. It explains inputs, optional overrides, and return value, making it complete enough for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description carries the burden. It explains all four parameters: query (prompt text), directory (working directory), model (optional alias or ID), timeout_seconds (per-call override). This adds meaning beyond the schema's raw type definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Send a query directly to the Gemini CLI', specifying the verb (send) and resource (Gemini CLI). The name 'consult_gemini' and sibling tools 'consult_gemini_with_files' and 'web_search' help distinguish its purpose as a direct query without file context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly mention when to use this tool vs. 'consult_gemini_with_files' or 'web_search'. It only implies usage for direct queries without files, lacking alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
consult_gemini_with_filesA
Send a query to the Gemini CLI with file context.
Args:
query: Prompt text forwarded to the CLI.
directory: Working directory used for resolving relative file paths.
files: File paths to include alongside the prompt. Paths must resolve
inside ``directory``; entries pointing outside it are skipped.
model: Optional model alias (``flash``, ``pro``) or full Gemini model id.
timeout_seconds: Optional per-call timeout override in seconds.
mode: ``"inline"`` streams truncated snippets; ``"at_command"`` emits
``@path`` directives so Gemini CLI resolves files itself.
Returns:
Gemini's response or an explanatory error string with any warnings.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | inline | |
| files | No | ||
| model | No | ||
| query | Yes | ||
| directory | Yes | ||
| timeout_seconds | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that files outside the working directory are silently skipped, that errors are returned as explanatory strings with warnings, and that per-call timeouts are possible. It stops short of stating auth/network prerequisites or what triggers truncation limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded one-line summary followed by structured Args/Returns sections; each parameter line earns its place. The Returns block partially duplicates the output schema but is short enough not to be wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter external-CLI tool, all parameters and the path-safety rule are covered, and an output schema exists so return values need little prose. The main gap is the absent routing guidance versus consult_gemini and no discussion of limits when many/large files are passed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the schema even lacks enum metadata, so the description must compensate fully — and it does, defining mode values ('inline' streams truncated snippets vs 'at_command' emits @path directives), model aliases (flash/pro), the path-resolution constraint on files, and the purpose of directory and timeout overrides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Send a query to the Gemini CLI with file context'), which clearly separates it from the sibling consult_gemini that lacks file context. It is clear, but it never explicitly contrasts itself with that sibling or names when file context is needed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use/when-not guidance or named alternative is given; the agent must infer from the tool name that files-bearing queries belong here rather than in consult_gemini. The mode explanation implies usage patterns but does not state selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
web_searchA
Ask Gemini queries with web search context.
Note: This uses Gemini CLI's automatic web search capability.
The model determines when to search based on query context.
Best-effort web search - not guaranteed for every query.
Args:
query: Search query or question to look up on the web
directory: Working directory for command execution
model: Optional model alias (flash, pro, or custom)
timeout_seconds: Optional per-call timeout override in seconds
Returns:
Gemini's response with potential web sources
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | ||
| query | Yes | ||
| directory | No | . | |
| timeout_seconds | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions automatic web search and best-effort nature, but omits details like rate limits, cost, or potential failure modes. Adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is front-loaded with purpose, followed by notes and args in a clear docstring format. Slightly verbose but well-structured; no redundant sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values are covered. Description explains tool behavior, parameters, and limitations. Complete for a web search tool with given complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description adds meaning to all 4 parameters: query as search term, directory as working directory, model as optional alias, timeout as per-call override. This compensates well for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The tool name 'web_search' and description 'Ask Gemini queries with web search context' clearly state the purpose. It distinguishes from siblings (consult_gemini, consult_gemini_with_files) by explicitly mentioning web search context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explains that the model determines when to search and that it's best-effort, giving guidance on when to use and expectations. However, it does not explicitly state when not to use or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
1 tool update
v1.3.0- Added
web_search
2 tool updates
v1.0.0- Changed
consult_gemini1 field changed- added
Input schema / properties / timeout_secondsAdded value: +{ + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Timeout Seconds" +}
- Changed
consult_gemini_with_files2 fields changed- added
Input schema / properties / modeAdded value: +{ + "default": "inline", + "title": "Mode", + "type": "string" +} - added
Input schema / properties / timeout_secondsAdded value: +{ + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Timeout Seconds" +}
2 tool updates
- First observed
consult_gemini - First observed
consult_gemini_with_files
TDQS
Scored across 3 tools
The three tools are mostly distinguishable: consult_gemini is plain, consult_gemini_with_files adds file context, and web_search adds search context. The overlap between the two consult_* tools is real—they differ only by file arguments—but the file/web/plain split gives an agent a reasonable basis for selection.
Two tools follow a clean consult_gemini / consult_gemini_with_files pattern, and web_search is a readable verb_noun name. The only deviation is web_search not carrying the consult_ prefix, but it describes a genuinely different capability so it still reads consistently.
Three tools is well-scoped for a thin bridge to a single CLI. Each tool maps to a distinct query mode rather than padding the surface, though the small count sits at the lower edge of the ideal range.
For a Gemini CLI passthrough the surface covers the main workflows: plain queries, file-context queries, and web-grounded queries. Minor gaps exist (no streaming/session continuity or config/inspection tool), but agents can accomplish the core task set without dead ends.
Maintenance
Related MCP Connectors
MCP server for AI dialogue using various LLM models via AceDataCloud
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
MCP server for GLM chat completions using Zhipu AI models via AceDataCloud
Official MCP server for Agentwork — delegate tasks to AI agents with human-in-the-loop
Related MCP Servers
- FlicenseBqualityDmaintenanceA lightweight MCP server that provides a unified interface to various LLM providers including OpenAI, Anthropic, Google Gemini, Groq, DeepSeek, and Ollama.6739-

Globalpingofficial
FlicenseNot gradedqualityBmaintenanceRemote MCP server that gives LLMs access to run network commands64-- AlicenseAqualityFmaintenanceA lightweight MCP server that enables AI coding assistants to interact with Google's Gemini AI through the official CLI.3MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server that lets Claude query Google's Gemini CLI as a sub-agent. Get second opinions, verify information, and cross-reference answers between AI models.-