| Name | gemini-cli-bridge JSON |
| Version |
0.1.2
JSON |
| download |
| home_page | None |
| Summary | MCP bridge for Gemini CLI and handy system/web tools |
| upload_time | 2025-09-11 05:17:53 |
| maintainer | None |
| docs_url | None |
| author | Your Name |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
cli
gemini
mcp
bridge
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Gemini CLI MCP Bridge
[English] | [简体中文](./README.zh-CN.md)
> 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:
```zsh
python3 --version
which gemini && gemini --version
```
## Install & Run
Clone first:
```zsh
git clone https://github.com/chaodongzhang/gemini_cli_bridge.git
cd gemini_cli_bridge
```
Option A (recommended, global install):
```zsh
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):
```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`.
Option B (one-off run via uvx):
```zsh
uvx --from . gemini-cli-bridge
```
Option C (run the script directly):
```zsh
python3 ./gemini_cli_bridge.py
```
## Use with common clients (stdio)
Examples below use stdio; adjust command/paths for your system.
### 1) Codex CLI (global TOML)
`~/.codex/config.toml`:
```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):
```json
{
"claude.mcpServers": {
"Gemini": {
"command": "gemini-cli-bridge",
"args": [],
"env": { "NO_COLOR": "1" }
}
}
}
```
### 3) Generic MCP CLI (for local testing)
```zsh
npm i -g @modelcontextprotocol/cli
mcp-cli --server gemini-cli-bridge
```
### 4) Claude Desktop (optional)
```json
{
"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:
```json
{
"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):
```json
{
"name": "GoogleSearch",
"arguments": {
"query": "Acme Corp",
"limit": 5
}
}
```
Use the alias to avoid naming conflicts in some IDEs:
```json
{
"name": "GeminiGoogleSearch",
"arguments": {
"query": "today ai industry news",
"limit": 5
}
}
```
Force built-in mode (no keys):
```json
{
"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`):
```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):
```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.
## 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
Raw data
{
"_id": null,
"home_page": null,
"name": "gemini-cli-bridge",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "CLI, Gemini, MCP, bridge",
"author": "Your Name",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/9f/47/c3e792f88e812b0be72c5478e0dab5e9eec10d71e0068eb02dd0dba5283f/gemini_cli_bridge-0.1.2.tar.gz",
"platform": null,
"description": "# Gemini CLI MCP Bridge\n\n[English] | [\u7b80\u4f53\u4e2d\u6587](./README.zh-CN.md)\n\n> 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.\n\nNote: In client UIs and configs, the server is displayed as \"Gemini\" while the command remains `gemini-cli-bridge` (or `uvx --from . gemini-cli-bridge`).\n\n## Features\n\n- Standard MCP (stdio) server\n- Thin wrappers for common Gemini CLI flows: version, prompt, WebFetch/Search, MCP management\n- Utilities: read/write files, list folders, simple web fetch, text search, optional Shell (disabled by default)\n- Runs with uv/uvx without manually installing dependencies\n\n## Prerequisites\n\n- Python 3.10+ (3.11+ recommended)\n- Gemini CLI installed and authenticated (used to call the actual model)\n- On macOS, ensure Homebrew bin is in PATH: `/opt/homebrew/bin`\n\nQuick checks:\n\n```zsh\npython3 --version\nwhich gemini && gemini --version\n```\n\n## Install & Run\n\nClone first:\n\n```zsh\ngit clone https://github.com/chaodongzhang/gemini_cli_bridge.git\ncd gemini_cli_bridge\n```\n\nOption A (recommended, global install):\n\n```zsh\nuv tool install --from . gemini-cli-bridge\n\n# Verify (should work from any directory)\ngemini-cli-bridge\n```\n\nAdd uv tools dir to PATH if needed.\n\n- macOS (zsh):\n\n ```zsh\n # Typically: $HOME/Library/Application Support/uv/tools/bin\n echo 'export PATH=\"$HOME/Library/Application Support/uv/tools/bin:$PATH\"' >> ~/.zshrc && source ~/.zshrc\n ```\n\n- Linux: usually `~/.local/bin`.\n\nOption B (one-off run via uvx):\n\n```zsh\nuvx --from . gemini-cli-bridge\n```\n\nOption C (run the script directly):\n\n```zsh\npython3 ./gemini_cli_bridge.py\n```\n\n## Use with common clients (stdio)\n\nExamples below use stdio; adjust command/paths for your system.\n\n### 1) Codex CLI (global TOML)\n\n`~/.codex/config.toml`:\n\n```toml\n[mcp_servers.Gemini]\ncommand = \"gemini-cli-bridge\"\nargs = []\n\n[mcp_servers.Gemini.env]\nNO_COLOR = \"1\"\n```\n\nNotes:\n\n- As of 2025-09-10, Codex only supports a global `~/.codex/config.toml`.\n- Restart Codex after changes. Use `gemini_version` as a quick health check.\n\n### 2) Claude Code (VS Code extension)\n\nUser Settings (JSON):\n\n```json\n{\n \"claude.mcpServers\": {\n \"Gemini\": {\n \"command\": \"gemini-cli-bridge\",\n \"args\": [],\n \"env\": { \"NO_COLOR\": \"1\" }\n }\n }\n}\n```\n\n### 3) Generic MCP CLI (for local testing)\n\n```zsh\nnpm i -g @modelcontextprotocol/cli\nmcp-cli --server gemini-cli-bridge\n```\n\n### 4) Claude Desktop (optional)\n\n```json\n{\n \"mcpServers\": {\n \"Gemini\": {\n \"command\": \"gemini-cli-bridge\",\n \"args\": [],\n \"env\": { \"NO_COLOR\": \"1\" }\n }\n }\n}\n```\n\n## Typical usage (from clients)\n\n- Version: `gemini_version`\n- Non-interactive prompt: `gemini_prompt(prompt=..., model=\"gemini-2.5-pro\")`\n- Advanced prompt with attachments/approval: `gemini_prompt_plus(...)`\n- Web fetch: `gemini_web_fetch(prompt, urls=[...])`\n- Manage Gemini CLI MCP: `gemini_mcp_list / gemini_mcp_add / gemini_mcp_remove`\n- Google search: `GoogleSearch(query=\"...\", limit=5)` (defaults to CLI built-in)\n- Alias to avoid tool name conflicts: `GeminiGoogleSearch(...)` (same args as `GoogleSearch`)\n\nReturn shape note (wrappers):\n- Gemini CLI wrappers now return structured JSON: `{ \"ok\", \"exit_code\", \"stdout\", \"stderr\" }`.\n Tools affected: `gemini_version`, `gemini_prompt`, `gemini_prompt_plus`, `gemini_prompt_with_memory`,\n `gemini_search`, `gemini_web_fetch`, `gemini_extensions_list`, `gemini_mcp_list/add/remove`.\n\nNotes about GoogleSearch:\n\n- By default it uses Gemini CLI\u2019s built-in GoogleSearch (no Google API keys needed, assuming you\u2019re logged in to the CLI).\n- If both `GOOGLE_CSE_ID` and `GOOGLE_API_KEY` are set (env or args), it switches to Google Programmable Search (CSE).\n- You can force the mode via `mode`: `\"gemini_cli\" | \"gcs\" | \"auto\"` (default auto).\n\n### MCP tool call examples\n\n`gemini_prompt_plus` payload example:\n\n```json\n{\n \"name\": \"gemini_prompt_plus\",\n \"arguments\": {\n \"prompt\": \"hello\",\n \"extra_args\": [\"--debug\", \"--proxy=http://127.0.0.1:7890\"]\n }\n}\n```\n\nMinimal `GoogleSearch` payload (defaults to CLI built-in):\n\n```json\n{\n \"name\": \"GoogleSearch\",\n \"arguments\": {\n \"query\": \"Acme Corp\",\n \"limit\": 5\n }\n}\n```\n\nUse the alias to avoid naming conflicts in some IDEs:\n\n```json\n{\n \"name\": \"GeminiGoogleSearch\",\n \"arguments\": {\n \"query\": \"today ai industry news\",\n \"limit\": 5\n }\n}\n```\n\nForce built-in mode (no keys):\n\n```json\n{\n \"name\": \"GoogleSearch\",\n \"arguments\": {\n \"query\": \"today ai industry news\",\n \"limit\": 5,\n \"mode\": \"gemini_cli\"\n }\n}\n```\n\n## Troubleshooting startup/handshake timeouts\n\n- Prefer installed command over `uvx --from .` to avoid cold-start dependency resolution.\n- Increase client startup/handshake timeouts if supported.\n- PATH issues on macOS: ensure `/opt/homebrew/bin` or set PATH in client env.\n\n## Make sure it uses CLI built-in search (avoid unintended CSE mode)\n\nPossible causes:\n\n- Another tool named `GoogleSearch` from a different server/extension.\n- Your environment sets both `GOOGLE_API_KEY` and `GOOGLE_CSE_ID`, which switches this bridge into CSE mode.\n\nWhat to do:\n\n1) Explicitly clear two vars in your MCP config\n\nCodex (`~/.codex/config.toml`):\n\n```toml\n[mcp_servers.Gemini]\ncommand = \"gemini-cli-bridge\"\nargs = []\n\n[mcp_servers.Gemini.env]\nPATH = \"/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin\"\nGOOGLE_API_KEY = \"\"\nGOOGLE_CSE_ID = \"\"\n```\n\nClaude Code (VS Code settings JSON):\n\n```json\n{\n \"claude.mcpServers\": {\n \"Gemini\": {\n \"command\": \"gemini-cli-bridge\",\n \"args\": [],\n \"env\": { \"GOOGLE_API_KEY\": \"\", \"GOOGLE_CSE_ID\": \"\" }\n }\n }\n}\n```\n\n1. Disambiguate in prompts\n\nAsk explicitly: \u201cUse GoogleSearch from MCP server \u2018Gemini\u2019 \u2026\u201d.\n\n1. Verify the path taken\n\n- Call `gemini_version` (should return `gemini --version`).\n- Call `GoogleSearch(query=\"test\", limit=3)`; the JSON should include `\"mode\":\"gemini_cli\"` if it used CLI built-in.\n\n1. Avoid tool name conflicts (optional)\n\nIf another `GoogleSearch` exists in your IDE, consider renaming this tool to `GeminiGoogleSearch` in code to remove ambiguity.\n\n## Developer Notes\n\n- Standardized gemini wrapper output\n - 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 }`.\n - When adding new Gemini CLI wrappers, focus on building the `cmd` list and delegate execution/formatting to the helper.\n\n- WebFetch behavior\n - Uses `requests` and respects `GEMINI_BRIDGE_MAX_OUT` for truncation via `get_max_out()`.\n - Blocks private/loopback/link-local targets using `_is_private_url`.\n - Returns `{ ok, status, content?, error? }`.\n\n- Running tests\n - `pytest -q` after installing dev deps, or run without installing by setting `PYTHONPATH`:\n - `PYTHONPATH=.::tests pytest -q`\n - A lightweight `tests/fastmcp.py` shim is included so tests run without installing external packages.\n\n## Configuration (env)\n\n- `GEMINI_BRIDGE_MAX_OUT` (int > 0): unified output truncation length. Default 200000.\n- `GEMINI_BRIDGE_DEFAULT_TIMEOUT_S` (int > 0): default timeout when a tool arg `timeout_s` is not provided.\n- `GEMINI_BRIDGE_EXTRA_PATHS`: colon-separated directories to append to PATH.\n- `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`.\n\nNotes\n- PATH cannot be overridden directly by tools; only appended via the whitelist above.\n- Shell tool remains disabled unless `MCP_BASH_ALLOW=1`.\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP bridge for Gemini CLI and handy system/web tools",
"version": "0.1.2",
"project_urls": null,
"split_keywords": [
"cli",
" gemini",
" mcp",
" bridge"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c94fcb61b5a45bf51fd304b53530ed6791f08282c2bda54234f0395612b2a458",
"md5": "2259f8ed18ee8391a07410101e24ceba",
"sha256": "6c1d9c945ddf4bae61c626f8ec204c7068e32fbc7b98718e059be8aef85b175d"
},
"downloads": -1,
"filename": "gemini_cli_bridge-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2259f8ed18ee8391a07410101e24ceba",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 12625,
"upload_time": "2025-09-11T05:17:52",
"upload_time_iso_8601": "2025-09-11T05:17:52.241271Z",
"url": "https://files.pythonhosted.org/packages/c9/4f/cb61b5a45bf51fd304b53530ed6791f08282c2bda54234f0395612b2a458/gemini_cli_bridge-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9f47c3e792f88e812b0be72c5478e0dab5e9eec10d71e0068eb02dd0dba5283f",
"md5": "61bc64c3fd4056e61d52bbf9cb69cfd3",
"sha256": "fb6ec38f1a6e0ece9d7528372c39bd8c952baa437ab1e319b8d8cedfd97143ac"
},
"downloads": -1,
"filename": "gemini_cli_bridge-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "61bc64c3fd4056e61d52bbf9cb69cfd3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 19086,
"upload_time": "2025-09-11T05:17:53",
"upload_time_iso_8601": "2025-09-11T05:17:53.462073Z",
"url": "https://files.pythonhosted.org/packages/9f/47/c3e792f88e812b0be72c5478e0dab5e9eec10d71e0068eb02dd0dba5283f/gemini_cli_bridge-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-11 05:17:53",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "gemini-cli-bridge"
}
