Gemini CLI 接入 MCP 服务器实战以 GitHub MCP Server 为例打通外部服务【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli本文以 Gemini CLI 官方教程docs/cli/tutorials/mcp-setup.md为主线带你从零完成一次完整的 MCPModel Context Protocol服务器接入准备 GitHub 凭据、在settings.json中通过 Docker 方式配置 GitHub MCP Server、用/mcp命令验证连接并直接用自然语言驱动 GitHub 工具。读完本篇你不仅能复现教程中的全部操作步骤还能结合源码理解 Gemini CLI 的传输选择、超时控制、工具命名与状态机等底层机制从而具备排查任意 MCP 服务器连接问题的能力。一、MCP 服务器是什么为什么需要它MCP 服务器是一个通过 Model Context Protocol 向 Gemini CLI 暴露工具tools、提示词prompts和资源resources的应用。它相当于模型与外部世界之间的桥梁发现工具通过标准化的 JSON Schema 定义列出可用工具及其参数执行工具用既定参数调用工具并拿到结构化响应访问资源读取服务器暴露的 URI 数据文件、API 载荷、报告等。借助 MCPGemini CLI 的能力可以延伸到内置工具之外——例如操作 GitHub 仓库、查询数据库、调用任意 API。本教程选择 GitHub MCP Server 作为示例因为它同时覆盖了三个最常见诉求Docker 容器化部署、PAT 鉴权、自然语言驱动的外部写操作创建 Issue、读取 PR。二、前置条件在开始之前确认以下环境已就绪已安装 Gemini CLI可执行gemini命令进入交互式界面Docker本教程的 GitHub MCP Server 以 Docker 容器方式运行因此宿主机必须安装并正在运行 DockerGitHub 个人访问令牌PAT一个具备 repo 权限的 PAT具体权限范围见下一节。三、准备凭据创建 GitHub PAT大多数 MCP 服务器都需要鉴权GitHub 使用 PAT。按以下步骤创建在 GitHub 的 Fine-grained personal access tokens 页面创建一个细粒度 PATfine-grained PAT权限授予建议最小化原则Metadata与Contents只读ReadIssues与Pull Requests读写Read/Write本教程的创建 Issue场景依赖写权限将令牌存入环境变量而不是写进配置文件macOS/Linuxexport GITHUB_PERSONAL_ACCESS_TOKENgithub_pat_...Windows (PowerShell)$env:GITHUB_PERSONAL_ACCESS_TOKENgithub_pat_...说明这个环境变量名GITHUB_PERSONAL_ACCESS_TOKEN是 GitHub MCP Server 官方约定的变量名Docker 容器内部通过它读取令牌。你只需保证宿主机环境里有这个名字的变量即可。四、配置 Gemini CLImcpServers 块详解Gemini CLI 通过在settings.json中声明mcpServers对象来获知有哪些 MCP 服务器。每个条目本质上是一条指令启动这个命令然后跟它的标准输入/输出对话。4.1 完整配置示例Docker GitHub MCP Server打开~/.gemini/settings.json用户级或项目根目录下的.gemini/settings.json项目级加入如下mcpServers块{ 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} } } } }逐字段解读字段作用command: docker要启动的可执行命令这里是docker说明该服务器走 Stdio 传输args: [...]传给docker的参数-i保持 stdin 打开Stdio 传输必需--rm退出后清理容器-e GITHUB_PERSONAL_ACCESS_TOKEN把宿主机同名变量注入容器env: { ... }通过${GITHUB_PERSONAL_ACCESS_TOKEN}在运行时从宿主机环境展开令牌值避免把密钥硬编码进配置文件服务器名github即配置键名会进入工具的全限定名mcp_github_*不要使用下划线命名服务器见第六节关键设计点令牌不落盘。env中的${VAR}语法由 Gemini CLI 的环境变量展开器在启动服务器时解析。这一点在源码中有明确实现——packages/core/src/tools/mcp-client.ts中通过expandEnvVars对env值做变量展开支持 POSIX 语法$VAR/${VAR}全平台与 Windows 语法%VAR%。4.2 环境变量展开与环境净化源码级补充从源码结构看Gemini CLI 在启动 MCP 服务器进程时并非把宿主机的整个环境直接透传。packages/core/src/tools/mcp-client.ts引用了sanitizeEnvironment做环境净化像GEMINI_API_KEY、GOOGLE_API_KEY这类核心密钥以及匹配*TOKEN*、*SECRET*、*PASSWORD*、*KEY*、*AUTH*等模式的变量会被默认从基础环境中剔除防止第三方 MCP 服务器意外读到你的敏感凭据。只有你在env中显式声明的变量才会传递给服务器——这正是本教程先 export 再用${GITHUB_PERSONAL_ACCESS_TOKEN}显式引用写法的底层原因显式声明即视为用户知情同意会跳过自动脱敏。4.3 替代方案用gemini mcp add命令写入配置除了手编 JSON仓库源码packages/cli/src/commands/mcp/add.ts表明 Gemini CLI 提供了gemini mcp add子命令等效地生成mcpServers条目# stdio 传输默认command args env gemini mcp add github docker \ -e GITHUB_PERSONAL_ACCESS_TOKEN${GITHUB_PERSONAL_ACCESS_TOKEN} \ -- run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server:latest # 可选参数来自 yargs 定义 # --scope user|project 写入用户级还是项目级 settings默认 project # --transport stdio|sse|http 传输类型默认 stdio # --header K: V sse/http 传输的自定义请求头 # --timeout ms 连接超时 # --trust 跳过所有工具调用确认 # --include-tools / --exclude-tools 工具白/黑名单注意--之后的参数会原样作为服务器参数追加源码中通过populate--与 middleware 合并实现。对于本教程的 Docker 场景由于参数较多且含-e注入手编settings.json的可读性更好两种方式的最终产物完全一致。五、验证连接/mcp 命令族重启 Gemini CLI 后它会按配置自动启动并发现 MCP 服务器。在交互界面输入/mcp list连接成功时应看到类似✓ github: docker ... - Connected的状态输出。如果显示Disconnected或错误信息先确认 Docker 守护进程在运行、PAT 有效。从packages/cli/src/ui/commands/mcpCommand.ts可以看到/mcp实际是一个子命令集合日常排障时都很有用命令作用/mcp或/mcp list列出全部服务器、连接状态、各服务器的工具/Prompt/资源、鉴权状态与错误信息后面跟文本则作为服务器名过滤/mcp desc在 list 基础上附带工具描述/mcp schema进一步附带参数 Schema/mcp reload别名 refresh调用McpClientManager.restart()重启所有 MCP 服务器并重新发现工具随后自动再执行一次 list/mcp auth [name]对需要 OAuth 的远程服务器发起认证本教程的 Docker 方案不需要/mcp enable name [--session]//mcp disable name [--session]启用/禁用某服务器受mcp.allowed/mcp.excluded全局策略约束改完自动重启服务器/mcp list输出的错误信息字段来自McpClientManager.getLastError(serverName)——即每个服务器最近一次连接/发现失败的原始报错是排障的第一现场。六、底层原理Gemini CLI 如何连接并使用一个 MCP 服务器理解这一节能让你在Disconnected时快速定位问题层。6.1 传输选择逻辑packages/core/src/tools/mcp-client.ts的connectToMcpServer()按配置字段决定传输方式配了command→StdioClientTransportspawn 子进程本教程的 Docker 场景走 stdin/stdout配了url→ 先按 Streamable HTTP 尝试失败则回退SSEClientTransport源码中对 HTTP 404/401 有明确的回退与 OAuth 分支配了httpUrl→ 直接StreamableHTTPClientTransport。默认请求超时为MCP_DEFAULT_TIMEOUT_MSEC 10 * 60 * 100010 分钟可在每个服务器配置中用timeout覆盖。6.2 状态机与发现流程每个服务器有一个MCPServerStatus状态机DISCONNECTED → CONNECTING → CONNECTED失败回落到DISCONNECTED另有BLOCKED/DISABLED两个管理态。连接成功后McpClient.discoverInto()依次做三件事拉取 prompts、发现 tools、发现 resources并注册进对应的全局注册表如果三者全空会抛出 No prompts, tools, or resources found 并断开。此外客户端会监听tools/list_changed等通知服务器端工具变化时无需手动/mcp reload也能自动刷新源码中带合批与 500ms 重试逻辑防止服务器先通知后就绪的竞态。6.3 工具命名为什么叫mcp_github_list_pull_requests所有 MCP 工具都会无条件加上完全限定名FQN前缀格式为mcp_{serverName}_{toolName}。这在packages/core/src/tools/mcp-tool.ts约 L595中实现并有packages/core/src/tools/tool-registry.test.ts等测试用例反复断言mcp_${serverName}_${toolName}的命名结果。因此教程中 Agent 调用的mcp_github_list_pull_requests正是服务器名github 原始工具名list_pull_requests拼接而来。由此产生一条重要的命名约束与 Policy Engine 相关服务器名不要含下划线。策略解析器按mcp_之后的第一个下划线切分 FQNmy_server这类命名会让通配规则静默失效。6.4 工具调用与确认模型选中某个 MCP 工具后由DiscoveredMCPTool处理确认逻辑配置里trust: true的服务器跳过所有确认否则弹出对话框可选仅本次、始终允许该工具、始终允许该服务器或取消。执行时用原始工具名调用服务器返回结果拆成两部分llmContent供模型上下文使用returnDisplay以 Markdown 形式展示给用户。七、使用新工具自然语言驱动 GitHub服务器连上后Agent 就多了GitHub 能力无需学习任何特殊命令直接用自然语言下达即可。场景 1列出 Pull RequestsPromptList the open PRs in the google/gemini-cli repository.Agent 的行为链条识别出请求匹配 GitHub 工具调用mcp_github_list_pull_requests把返回数据整理后呈现给你。场景 2创建 IssuePromptCreate an issue in my repo titled Bug: Login fails with the description See logs.由于 PAT 授予了 Issues 的 Read/Write 权限这一步会真正在仓库中创建 Issue——这也是最小化权限的重要示范不需要给仓库完整的 admin 权限只给实际用到的 Issues/PR 写权限。八、故障排查Troubleshooting症状处理方法服务器起不来在终端手动执行settings.json里那条 docker 命令看是否输出 image not found 等错误确认 Docker 守护进程在跑、镜像可拉取工具找不到执行/mcp reload即refresh强制 CLI 重新向服务器查询其能力源码层面等价于mcpClientManager.restart()geminiClient.setTools() 斜杠命令重载状态是 Disconnected 且 list 里有报错/mcp list的 error 字段会给出最近一次连接失败的原始错误配合--debug启动 CLI交互模式按 F12 打开调试控制台查看传输层日志工具列表比预期少检查是否被includeTools/excludeTools过滤excludeTools优先或全局mcp.allowed/mcp.excluded名单或服务器被/mcp disable禁用凭据未生效确认环境变量已 export 到启动 CLI 的同一个 shellenv中的${VAR}在变量缺失时会展开为空字符串补充一条来自源码的行为细节服务器进程若不提供任何 tools/prompts/resources连接会在发现阶段被关闭状态回落DISCONNECTED——所以连上了但什么工具都没有通常意味着服务器本身没注册工具或注册名被过滤规则挡掉了。九、总结与延伸阅读回顾本教程完成的完整闭环凭据细粒度 PAT 宿主机环境变量令牌不写入配置文件配置settings.json中mcpServers.github声明 Docker 启动命令与${VAR}环境展开验证重启 CLI 后/mcp list确认Connected失败时看 error 字段并手动跑 docker 命令使用自然语言触发mcp_github_list_pull_requests等 FQN 工具维护/mcp reload、/mcp enable/disable管理服务器生命周期。如果你想继续深入建议阅读以下仓库内的配套文档MCP 服务器完整参考三种传输Stdio/SSE/Streamable HTTP、OAuth 自动发现、authProviderType各取值、headers、工具过滤、Schema 清洗与发现流程的深度剖析以及远程服务器配置示例MCP 资源工具用server://...引用远程资源设置项参考mcp.allowed/mcp.excluded等全局开关的完整说明核心实现源码mcp-client.ts连接、传输选择、状态机、通知刷新、mcp-tool.ts工具包装与 FQN 命名、mcpCommand.ts/mcp命令族、mcp add 命令。掌握这条配置 → 发现 → 命名 → 确认 → 执行的主线后接入 Slack、Postgres、Google Drive 等任意 MCP 服务器都只是替换command/url与env的差异其余流程完全一致。【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考