Gemini CLI 的 MCP 服务器

本文概述如何在 Gemini CLI 中配置与使用 Model Context Protocol (MCP) 服务器。

MCP 服务器是什么？

MCP 服务器通过 MCP 协议向 CLI 暴露工具与资源，使模型能够与本地环境或外部服务交互：

  • 发现工具：返回工具清单及参数 Schema；
  • 执行工具：接受参数调用并返回结构化响应；
  • 访问资源：可暴露数据读取能力（CLI 当前主要聚焦于工具调用）。

借助 MCP，可扩展 CLI 与数据库、API、自定义脚本等系统交互。

核心架构

  • 发现层 (mcp-client.ts)：discoverMcpTools() 读取 settings.json 中的 mcpServers 配置，建立连接、获取工具定义、校验 Schema 并注册到全局工具注册表。
  • 执行层 (mcp-tool.ts)：每个工具被封装成 DiscoveredMCPTool，负责审批逻辑、调用执行、结果处理与状态维护。
  • 传输模式：支持 stdio（子进程 stdin/stdout）、sse、streamable http。

配置 MCP 服务器

在 settings.json 中使用：

{
  "mcp": {
    "allowed": ["trusted"],
    "excluded": ["experimental"]
  },
  "mcpServers": {
    "trusted": {
      "command": "node",
      "args": ["server.js"],
      "env": {"API_KEY": "$MY_TOKEN"},
      "cwd": "./servers/trusted",
      "timeout": 30000,
      "transport": "stdio",
      "trust": false
    }
  }
}
  • mcp：全局白名单/黑名单、默认命令。
  • mcpServers：逐个定义服务器；常见字段：
    • command / args / cwd：用于 stdio 传输；
    • env：环境变量（支持引用 $VAR）；
    • url + headers：用于 http / sse；
    • transport：stdio/http/sse；
    • timeout：连接/执行超时时间（毫秒）；
    • trust：设为 true 可跳过工具确认（谨慎使用）；
    • includeTools / excludeTools：过滤要暴露的工具；
    • description：用于 /tools 输出中的说明。

执行流程

  1. CLI 启动时根据 mcpServers 连接各服务器；
  2. 获取工具 Schema，并注册为 mcpServerName__toolName；
  3. 当模型请求该工具时，CLI 会遵循确认策略向服务器发送调用；
  4. 返回结果同时用于模型上下文与 CLI 展示。

认证与安全

  • 可通过 env、headers 注入认证信息；
  • 建议将 trust 设为 false，由用户确认敏感操作；
  • 在沙箱环境中使用 MCP 时，需确保服务器在沙箱内可访问。

远程 MCP 示例

  • 本地脚本（stdio） 
    {
  "command": "python",
  "args": ["server.py"],
  "env": {"API_KEY": "$LOCAL_API_KEY"}
}
  • HTTP 
    {
  "transport": "http",
  "url": "https://api.example.com/mcp",
  "headers": ["Authorization: Bearer $TOKEN"]
}
  • SSE 
    {
  "transport": "sse",
  "url": "https://api.example.com/sse",
  "headers": ["X-Org: example"]
}

使用 CLI 管理 MCP

Gemini CLI 内置 gemini mcp 命令，方便在用户或项目配置中增删服务器。

添加服务器

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

常见选项：

  • -s, --scope [project|user]：指定写入项目配置或用户配置（默认 project）。
  • -t, --transport [stdio|http|sse]：指定传输方式。
  • -e, --env KEY=value：写入环境变量。
  • -H, --header "Header: Value"：为 HTTP/SSE 传输追加请求头，可重复多次。
  • --timeout、--trust、--description、--include-tools、--exclude-tools：分别控制超时、是否信任、描述以及工具的包含/排除列表。

示例：

# 添加本地 stdio 服务器
gemini mcp add my-server /path/to/server --flag value

# 添加 HTTP 服务器
gemini mcp add --transport http my-http https://api.example.com/mcp --header "Authorization: Bearer $TOKEN"

# 添加 SSE 服务器
gemini mcp add --transport sse my-sse https://api.example.com/sse/

查看与删除

gemini mcp list     # 查看全部服务器
gemini mcp remove <name>  # 删除某个配置

提示模板（MCP prompts）

若服务器支持 prompts/list 与 prompts/get，CLI 会在 /prompts 中列出可用模板，并允许通过 /prompt use <name> 引用，支持自定义参数。服务器负责模板渲染，CLI 将结果交给模型执行。

常见问题

  • 多个 IDE/终端使用同一工作区：为避免冲突，可利用 mcp.allowed 仅允许当前场景需用的服务器。
  • 沙箱中使用：需确保服务器与依赖位于沙箱镜像内，或通过网络访问可达。
  • 连接失败：检查 timeout、命令路径、环境变量是否正确；必要时在 CLI 中开启 DEBUG=1 观察日志。

通过 MCP 服务器，你可以将自定义工具和外部服务无缝引入 Gemini CLI，将其变成高度可扩展的自动化助手。