Gemini CLI MCP 怎么配置？从安装检查到连接验证

更新于 2026-10-31 · runapi.cfd

简答：Gemini CLI 配置 MCP，核心是把服务器写入用户级或项目级 settings.json 的 mcpServers 对象。最短闭环是：确认 Node.js 与 Gemini CLI 可用→写入一个 MCP 配置→重启 CLI→执行 /mcp list→确认 Connected 和工具列表。本文按 2026 年 10 月 31 日核验的官方文档整理；本站是第三方 AI API 接入指南站，不是 Gemini CLI 官方站。

定义：MCP 是让 Gemini CLI 发现并调用外部工具、数据源或 API 的协议；Gemini CLI 可通过 command、httpUrl 或 url 分别连接 stdio、Streamable HTTP 和 SSE 服务器。

先看这一张：你应该选哪种 MCP 传输方式

如果你只想先把配置跑通，优先从本地 stdio 开始；如果服务方给的是新的流式 HTTP 地址，使用 httpUrl；如果服务方明确提供 SSE 地址，使用 url。不要根据 URL 中是否出现 stream 自行判断传输方式，应以 MCP 服务提供方文档为准。Gemini CLI 官方 MCP 文档明确列出了这三种连接方式及对应字段。查看官方 MCP Server 配置说明

最小成功判定：保存配置后重启 Gemini CLI，执行 /mcp list；服务器显示 Connected，并且能看到工具名称或工具描述，才算完成连接。官方教程也采用重启 CLI 后执行 /mcp list 的验证流程。

安装与版本检查：先把 Gemini CLI 本身跑通

本文核验时，Gemini CLI 官方安装文档列出的运行时要求是 Node.js 20.0.0 或更高版本，并支持 Bash、Zsh 或 PowerShell。官方推荐的 npm 全局安装命令是 npm install -g @google/gemini-cli，也提供 Homebrew、MacPorts、Anaconda 和 npx 等方式。具体系统建议和安装方式可能随文档变化，发布前应再次查看官方页面。查看 Gemini CLI 官方安装文档

1. 检查 Node.js：node --version。版本低于 20 时，先升级 Node.js。
2. 安装 CLI：npm install -g @google/gemini-cli。
3. 确认命令可用：gemini --version。
4. 启动 CLI：gemini，按当前终端提示完成认证。
5. 查看当前版本帮助：gemini mcp --help。如果命令参数与本文不同，以本机帮助和当前官方命令文档为准。

Windows、macOS、Linux 的路径和 PATH 检查

• macOS/Linux：用户配置通常位于 ~/.gemini/settings.json；可用 echo $HOME 查看当前用户目录。
• Windows PowerShell：同样使用用户目录下的 .gemini\settings.json；可用 echo $HOME 查看 PowerShell 识别的用户目录。
• Windows CMD：可用 echo %USERPROFILE% 查看用户目录；环境变量引用使用 %VAR_NAME% 时，只适用于 Windows 配置语法。
• 命令找不到：分别运行 where gemini（Windows）或 which gemini（macOS/Linux）。如果 npm 已安装但找不到命令，检查 npm 全局可执行目录是否加入 PATH，然后重新打开终端。

安装文档还列出了 macOS 15+、Windows 11 24H2+、Ubuntu 20.04+ 等推荐系统规格；这些属于官方当前建议，不代表其他系统一定无法运行。查看官方系统要求与安装方法

settings.json 写在哪里：用户级与项目级配置

Gemini CLI 当前配置文档列出用户级、项目级和系统级等配置层。普通用户最常用的是用户级 ~/.gemini/settings.json，以及项目根目录下的 .gemini/settings.json。用户级配置适合多个项目共用；项目级配置适合只在当前仓库启用的 MCP 服务器。查看官方配置文件位置和优先级

配置优先级不是“项目文件整体覆盖用户文件”。官方文档给出的顺序是：默认值、系统默认文件、用户设置、项目设置、系统设置、环境变量、命令行参数；因此在同名配置或服务器发生冲突时，项目级设置通常优先于用户级设置，但更高优先级的系统设置、环境变量或命令行参数仍可能覆盖它。

最小 mcpServers 结构

下面是用于理解字段的本地 stdio 模板。./mcp-servers/python 和 my_mcp_server 必须替换成你实际安装或编写的 MCP 服务，不能直接当作现成服务器运行。

{ "mcpServers": { "local-tools": { "command": "python", "args": ["-m", "my_mcp_server"], "cwd": "./mcp-servers/python", "timeout": 15000, "trust": false } } }

官方配置字段中，command、url、httpUrl 三者至少使用一个；args、cwd、timeout、trust、includeTools 和 excludeTools 属于可选字段。trust: true 会绕过该服务器的工具调用确认，不建议在不了解服务器行为时开启。查看官方字段定义

首个可核验示例：使用官方文档中的 GitHub MCP 配置

如果你希望使用一个官方教程明确给出的完整示例，可以采用 GitHub MCP Server 的 Docker 配置。这个路线需要 Docker、GitHub Personal Access Token，以及当前终端能够读取的环境变量；如果你没有 Docker 或 GitHub Token，可以先使用上一节的本地 stdio 模板熟悉字段，不要把占位配置误认为可直接运行的服务。

1. 设置环境变量

macOS/Linux：

export GITHUB_PERSONAL_ACCESS_TOKEN="YOUR_GITHUB_TOKEN"

Windows PowerShell：

$env:GITHUB_PERSONAL_ACCESS_TOKEN="YOUR_GITHUB_TOKEN"

Windows CMD：

set GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_GITHUB_TOKEN

上面的 YOUR_GITHUB_TOKEN 只是占位符。不要把真实 Token 粘贴进文章、截图、仓库或命令示例中。

2. 写入 settings.json

下面的配置来自 Gemini CLI 官方 MCP 设置教程，使用 Docker 运行 GitHub MCP Server。这里的 latest 是官方示例采用的镜像标签；如果你需要稳定复现，应关注官方镜像发布说明，并在变更前测试，而不要把 latest 理解为固定版本。

{ "mcpServers": { "github": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server:latest" ], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}" } } } }

这里的含义是：env 通过 Gemini CLI 配置中的变量引用读取启动 CLI 的进程环境；Docker 参数中的 -e GITHUB_PERSONAL_ACCESS_TOKEN 再把该变量映射进容器。它是官方示例的一种写法，不代表所有 Docker MCP 服务都必须这样配置。官方文档说明，$VAR_NAME 和 ${VAR_NAME} 可用于配置值，Windows 还支持 %VAR_NAME%。查看官方 GitHub MCP Docker 示例

3. 重启并验证

1. 确认 Docker Desktop 或 Docker 服务正在运行。
2. 确认当前终端能读取变量：macOS/Linux 使用 printf '%s\n' "$GITHUB_PERSONAL_ACCESS_TOKEN"，PowerShell 使用 if ($env:GITHUB_PERSONAL_ACCESS_TOKEN) { 'set' } else { 'missing' }。不要打印真实 Token。
3. 保存 JSON 后，完全退出并重新启动 gemini。
4. 在会话中执行 /mcp list。
5. 看到 github ... Connected，并能看到工具列表后，再尝试自然语言请求。

官方教程给出的验证路径也是重启 Gemini CLI 后执行 /mcp list；如果显示 Disconnected，先检查 Docker 和 Token 是否有效。查看官方验证步骤

HTTP、SSE 和环境变量的正确写法

远程服务必须由服务提供方明确告诉你使用 Streamable HTTP 还是 SSE。Gemini CLI 对应的字段分别是 httpUrl 和 url，认证请求头使用 headers。以下只展示字段模板，域名和 Token 并非已核验的公共服务。

Streamable HTTP 模板

{ "mcpServers": { "remote-http": { "httpUrl": "https://example.invalid/mcp", "headers": { "Authorization": "Bearer $MCP_TOKEN" }, "timeout": 30000 } } }

SSE 模板

{ "mcpServers": { "remote-sse": { "url": "https://example.invalid/sse", "headers": { "Authorization": "Bearer ${MCP_TOKEN}" }, "timeout": 30000 } } }

官方配置文档说明，环境变量引用发生在 settings.json 加载时；因此真实变量必须存在于启动 Gemini CLI 的环境中。不要在 gemini mcp add 命令中直接展开真实 Token，因为它可能进入命令历史或进程参数。更稳妥的做法是先设置本地环境变量，再用配置文件引用变量，或使用当前版本支持的安全认证流程。

如果远程 MCP 服务使用 OAuth，可在会话中执行 /mcp auth serverName；当前命令参考将其定义为用于 OAuth-enabled MCP 服务器的认证命令。查看官方 /mcp 命令参考

用 gemini mcp 命令添加、查看和排错

Gemini CLI 也支持通过命令行写入 MCP 配置。官方当前语法是：

gemini mcp add [options] <name> <commandOrUrl> [args...]

• 项目级配置：gemini mcp add --scope project ...。
• 用户级配置：gemini mcp add --scope user ...。
• 本地 stdio：默认传输方式，命令放在服务器名称后面。
• Streamable HTTP：使用 --transport http。
• SSE：使用 --transport sse。
• HTTP 或 SSE 请求头：使用 --header。

不带真实密钥的命令模板

gemini mcp add --scope project python-server python server.py

gemini mcp add --scope user --transport http remote-http https://example.invalid/mcp

gemini mcp add --scope project --transport sse remote-sse https://example.invalid/sse

gemini mcp list

官方命令参考显示，gemini mcp list 会列出已配置服务器、配置细节和连接状态；stdio 服务器只有在当前文件夹受信任时才会按连接状态测试，必要时可使用 gemini trust 信任当前目录。交互会话中则使用 /mcp list、/mcp desc 和 /mcp schema 查看服务器、工具描述及参数结构；/mcp reload 用于重新加载服务器并重新发现工具。查看当前命令行为

按现象排查：Disconnected、工具为空和 JSON 错误

当前官方命令文档说明，MCP 启动错误默认可能减少输出；执行交互命令如 /mcp list，或使用 gemini mcp list，可以查看连接状态和错误信息。这里应把它理解为状态与错误查看入口，而不是保证解决所有故障的通用诊断器。查看官方 MCP 排错说明

固定排错闭环：确认配置文件范围→确认字段与传输方式→确认 command 或 URL→确认变量和认证→确认目录信任或 Docker→重启 CLI→执行 /mcp list→再查看工具描述和 schema。

常见问题

Gemini CLI MCP 配置写在哪个文件？

多项目共用时，优先考虑用户级 ~/.gemini/settings.json；只想让当前项目使用时，写入项目根目录下的 .gemini/settings.json。项目配置优先于用户配置，但系统设置、环境变量和命令行参数还可能具有更高优先级，不能理解为项目文件整体覆盖用户文件。

Windows CMD 和 PowerShell 的环境变量写法一样吗？

不一样。PowerShell 使用 $env:VAR_NAME=value，CMD 使用 set VAR_NAME=value。在 settings.json 中，官方文档支持 $VAR_NAME 和 ${VAR_NAME}，Windows 还支持 %VAR_NAME%；不要把 Shell 命令语法和 JSON 配置语法混为一谈。

为什么 MCP 配置后显示 Disconnected？

先执行 /mcp list 或 gemini mcp list 查看状态。stdio 重点检查当前目录信任、命令路径、参数和工作目录；Docker 重点检查 Docker 服务、变量和 Token；HTTP/SSE 重点检查字段、端点路径、认证头和网络。

可以把 Token 直接写进 settings.json 吗？

不建议。Gemini CLI 官方配置文档支持用环境变量引用配置值，优先把真实 Token 留在本地环境中，再在 JSON 中引用变量。不要把密钥提交到仓库、写入公开日志或直接拼接进命令历史。

修改 settings.json 后需要重启吗？

对初学者来说，最稳定的闭环是保存 JSON、完全退出 Gemini CLI、重新启动，再执行 /mcp list。如果当前版本支持 /mcp reload，也可以用它重新加载服务器并重新发现工具；若命令行为不同，以 /mcp --help 和当前官方文档为准。

stdio、HTTP 和 SSE 到底怎么选？

本地脚本、Python、Node.js 或 Docker 通常使用 stdio，对应 command；服务方提供 Streamable HTTP 端点时使用 httpUrl；服务方明确提供 SSE 端点时使用 url。传输方式必须以服务器文档为准。

常见问题

Gemini CLI MCP 配置写在哪个文件？

多项目共用时使用用户级 ~/.gemini/settings.json；只对当前项目生效时使用项目根目录下的 .gemini/settings.json。项目设置优先于用户设置，但系统设置、环境变量和命令行参数可能继续覆盖它。

Windows CMD、PowerShell 的 Token 写法有什么区别？

PowerShell 使用 $env:VAR_NAME=value，CMD 使用 set VAR_NAME=value。settings.json 中则使用官方支持的 $VAR_NAME、${VAR_NAME}，Windows 还可使用 %VAR_NAME%。

Gemini CLI MCP 为什么显示 Disconnected？

先执行 /mcp list 或 gemini mcp list。stdio 检查目录信任、command、args 和 cwd；Docker 检查 Docker、环境变量和 Token；HTTP/SSE 检查字段、端点、认证头和网络。

Connected 但没有工具怎么办？

执行 /mcp desc 或 /mcp schema 查看工具发现结果，检查 includeTools 和 excludeTools 是否过滤了工具，再执行 /mcp reload 重新发现。

MCP Token 应该怎样保存？

优先把真实 Token 放在本地环境变量中，在 settings.json 里使用变量引用，避免硬编码到 JSON、命令历史、日志或代码仓库。

相关阅读

• Gemini CLI 转 API：核对 Base URL、Key 和模型
• API Key 安全：从本地开发到生产的保护清单
• Open WebUI 配置 OpenAI 兼容 API

参考资料

1. Gemini CLI 官方安装、系统要求与运行方式
2. Gemini CLI 官方配置文件位置、优先级与环境变量（google-gemini.github.io）
3. Gemini CLI 官方 MCP Server 字段、传输方式与管理命令
4. Gemini CLI 官方 GitHub MCP Docker 设置教程
5. Gemini CLI 官方 /mcp 命令参考