jamubc/gemini-mcp-tool · 上手攻略

仓库：jamubc/gemini-mcp-tool
链接：https://github.com/jamubc/gemini-mcp-tool
分类：skill（MCP Server / AI 工具链集成）
作者：Jay
更新：2026-08-15

是什么

gemini-mcp-tool 是一个 MCP（Model Context Protocol）服务器，它让 AI 助手（如 Claude Code）能够直接调用 Google Gemini CLI 的强大分析能力，对大文件、代码库进行深度理解与问答。本质上是一个桥接层：AI 助手通过 MCP 协议把文件路径和自然语言指令发送给 Gemini CLI，利用 Gemini 的大 Token 上下文窗口完成分析任务。

2026 年 6 月 18 日 Google 宣布 Gemini CLI 正式退役（免费用户），该项目已自动切换至其继任者 Antigravity CLI（agy），大多数用户无需做任何改动。

解决什么问题

大文件 / 代码库理解：Gemini CLI 支持超大上下文（数百万 Token），直接分析整个代码库无需拆分
AI 助手深度分析能力扩展：让 Claude Code 等工具直接调用 Gemini 进行多角度分析
安全沙箱执行：sandbox 模式可在隔离环境中安全运行用户代码，不影响主机
@ 语法文件引用：通过 @path/to/file 直接引用本地文件，Gemini 自动理解上下文

快速安装

前置依赖

Node.js ≥ 16.0.0（官方建议 v18+）
Gemini CLI 或 Antigravity CLI（agy）（见下方说明）

# macOS / Linux 安装 agy（Google Gemini CLI 退役后默认使用）
curl -fsSL https://antigravity.google/cli/install.sh | bash

# 首次运行需要登录
agy

⚠️ 付费 API Key 用户（企业/标准许可）若仍想用原 Gemini CLI，设置环境变量 GEMINI_MCP_BACKEND=gemini 即可保持原有行为。

配置到 Claude Code

claude mcp add gemini-cli -- npx -y gemini-mcp-tool

配置到 Claude Desktop

打开配置文件： - macOS：~/Library/Application Support/Claude/claude_desktop_config.json - Windows：%APPDATA%\Claude\claude_desktop_config.json - Linux：~/.config/Claude/claude_desktop_config.json

添加以下配置：

{
  "mcpServers": {
    "gemini-cli": {
      "command": "npx",
      "args": ["-y", "gemini-mcp-tool"]
    }
  }
}

⚠️ Windows 用户将 -y 替换为 --yes（完整参数：npx --yes gemini-mcp-tool）。

全局安装（可选）

npm install -g gemini-mcp-tool
# 或
pnpm add -g gemini-mcp-tool

全局安装后 MCP 配置改为：

"command": "gemini-mcp"

核心用法

环境变量配置

变量	可选值	默认	说明
`GEMINI_MCP_BACKEND`	`gemini` / `agy`	`agy`（2026-06-18 后自动切换）	指定后端
`AGY_CLI_PATH`	完整路径字符串	在 PATH 中查找	agy 二进制文件路径
`GEMINI_MCP_TIMEOUT`	整数（分钟）	`45`	CLI 运行超时时间

Claude Code 内命令

在 Claude Code 中直接使用：

/analyze prompt:@src/main.js 解释这段代码
/analyze prompt:请用 web 搜索找最新 AI 新闻
/sandbox prompt:创建一个 Python 脚本处理 CSV 数据
/ping  # 测试连接
/help  # 显示帮助

直接调用 MCP 工具

ask-gemini：向 Gemini 提问或分析文件（必填 prompt，可选 model / sandbox）
sandbox-test：在沙箱中安全执行代码
Ping：连接测试
Help：显示帮助

示例（prompt 中用 @ 引用文件）：

ask gemini to analyze @src/main.js and explain what it does
ask gemini to summarize @. the current directory
use gemini to search for latest tech news

模型选择

默认使用 gemini-2.5-pro（可通过 model 参数覆盖）。agy 后端目前仅支持 Gemini 3.5 Flash（实验性）。

典型适用场景

大型代码库整体分析：用 @ 引用整个目录，Gemini 超大上下文窗口一次性理解全貌
跨语言代码审查：同时分析 TypeScript + Python + Go 混合项目
安全代码执行：在 sandbox 模式下运行来历不明的脚本，无需担心主机安全
Claude Code 增强：在 Claude Code 中直接调用 Gemini 的搜索和推理能力
快速技术调研：让 Gemini 搜索最新行业动态，汇总给 Claude

坑与注意

问题	说明
agy 后端实验性	目前仅支持 Gemini 3.5 Flash，`/sandbox` 模式工具执行未在 `-p` 模式中沙箱化
Gemini CLI 2026-06-18 已退役	免费用户默认迁移到 agy；若已是付费用户需设置 `GEMINI_MCP_BACKEND=gemini`
stdout 模式	agy 回复来自 stdout，transcript 恢复仅为 fallback
工具未测试	除 Claude Code 外其他 MCP 客户端兼容性未全面测试
赞助商 / 第三方	本工具非 Google 官方项目，为第三方独立开发

与同类对比

工具	特点	与 gemini-mcp-tool 的区别
`anthropics/claude-code`	官方 Claude Code	本身是 Agent，不依赖外部 CLI
MCP 官方生态（如 Filesystem、Git）	基础文件操作	不具备大上下文分析能力
Gemini CLI 直接使用	独立使用 Gemini	无 Agent 集成，需手动操作
gemini-mcp-tool	桥接 Gemini → AI 助手	让 Claude 直接调用 Gemini 大上下文能力

一句话：如果你已经在用 Claude Code，想借助 Gemini 的超大上下文窗口分析整个代码库，gemini-mcp-tool 是目前最直接的低成本方案。

一句话结论

gemini-mcp-tool 是一座桥，让 Claude Code 等 MCP 客户端直接调用 Gemini 的超大上下文分析能力，适合需要一次性理解整个代码库的场景——注意 agy 后端目前实验性，sandbox 工具执行尚未完全隔离，付费用户可回退 GEMINI_MCP_BACKEND=gemini 保持原行为。