技术文档

主题

Gemini CLI 中的 MCP 服务器 ​

本文档提供了在 Gemini CLI 中配置和使用 Model Context Protocol (MCP) 服务器的指南。

什么是 MCP 服务器？ ​

MCP 服务器是一个应用程序，通过 Model Context Protocol 向 Gemini CLI 公开工具和资源，允许它与外部系统和数据源交互。MCP 服务器充当 Gemini 模型与你的本地环境或其他服务（如 API）之间的桥梁。

MCP 服务器使 Gemini CLI 能够：

  • 发现工具： 通过标准化的模式定义列出可用工具、它们的描述和参数。
  • 执行工具： 使用定义的参数调用特定工具并接收结构化响应。
  • 访问资源： 从服务器公开的特定资源（文件、API 负载、报告等）读取数据。

通过 MCP 服务器，你可以扩展 Gemini CLI 的功能，执行超出其内置功能的操作，例如与数据库、API、自定义脚本或专门工作流交互。

如何设置你的 MCP 服务器 ​

Gemini CLI 使用 settings.json 文件中的 mcpServers 配置来定位和连接 MCP 服务器。此配置支持具有不同传输机制的多个服务器。

在 settings.json 中配置 MCP 服务器 ​

在你的 settings.json 文件中添加 mcpServers 对象：

json
{
  "mcpServers": {
    "serverName": {
      "command": "path/to/server",
      "args": ["--arg1", "value1"],
      "env": {
        "API_KEY": "$MY_API_TOKEN"
      },
      "cwd": "./server-directory",
      "timeout": 30000,
      "trust": false
    }
  }
}

配置属性 ​

每个服务器配置支持以下属性：

必需（以下之一） ​

  • command（字符串）：Stdio 传输的可执行文件路径
  • url（字符串）：SSE 端点 URL（例如 "http://localhost:8080/sse"）
  • httpUrl（字符串）：HTTP 流端点 URL

可选 ​

  • args（字符串数组）：Stdio 传输的命令行参数
  • headers（对象）：使用 url 或 httpUrl 时的自定义 HTTP 头
  • env（对象）：服务器进程的环境变量
  • cwd（字符串）：Stdio 传输的工作目录
  • timeout（数字）：请求超时（毫秒）（默认：600,000ms = 10 分钟）
  • trust（布尔值）：当为 true 时，绕过此服务器的所有工具调用确认（默认：false）
  • includeTools（字符串数组）：要从此 MCP 服务器包含的工具名称列表
  • excludeTools（字符串数组）：要从此 MCP 服务器排除的工具名称列表

示例配置 ​

Python MCP 服务器（stdio） ​

json
{
  "mcpServers": {
    "pythonTools": {
      "command": "python",
      "args": ["-m", "my_mcp_server", "--port", "8080"],
      "cwd": "./mcp-servers/python",
      "env": {
        "DATABASE_URL": "$DB_CONNECTION_STRING"
      },
      "timeout": 15000
    }
  }
}

Node.js MCP 服务器（stdio） ​

json
{
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["dist/server.js", "--verbose"],
      "cwd": "./mcp-servers/node",
      "trust": true
    }
  }
}

基于 Docker 的 MCP 服务器 ​

json
{
  "mcpServers": {
    "dockerizedServer": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "API_KEY",
        "-v",
        "${PWD}:/workspace",
        "my-mcp-server:latest"
      ],
      "env": {
        "API_KEY": "$EXTERNAL_SERVICE_TOKEN"
      }
    }
  }
}

基于 HTTP 的 MCP 服务器 ​

json
{
  "mcpServers": {
    "httpServer": {
      "httpUrl": "http://localhost:3000/mcp",
      "timeout": 5000
    }
  }
}

如何与你的 MCP 服务器交互 ​

使用 /mcp 命令 ​

/mcp 命令提供有关你的 MCP 服务器设置的全面信息：

bash
/mcp

这将显示：

  • 服务器列表： 所有配置的 MCP 服务器
  • 连接状态： CONNECTED、CONNECTING 或 DISCONNECTED
  • 服务器详情： 配置摘要（不包括敏感数据）
  • 可用工具： 每个服务器的工具列表及描述
  • 发现状态： 整体发现过程状态

工具使用 ​

一旦发现，MCP 工具就像内置工具一样可供 Gemini 模型使用。模型将自动：

  1. 根据你的请求选择适当的工具
  2. 显示确认对话框（除非服务器受信任）
  3. 使用适当的参数执行工具
  4. 以用户友好的格式显示结果

状态监控和故障排除 ​

连接状态 ​

MCP 集成跟踪几种状态：

服务器状态（MCPServerStatus） ​

  • DISCONNECTED： 服务器未连接或有错误
  • CONNECTING： 连接尝试进行中
  • CONNECTED： 服务器已连接并准备就绪

常见问题和解决方案 ​

服务器无法连接 ​

症状： 服务器显示 DISCONNECTED 状态

故障排除：

  1. 检查配置： 验证 command、args 和 cwd 是否正确
  2. 手动测试： 直接运行服务器命令以确保它工作
  3. 检查依赖项： 确保安装了所有必需的包
  4. 查看日志： 在 CLI 输出中查找错误消息
  5. 验证权限： 确保 CLI 可以执行服务器命令

未发现工具 ​

症状： 服务器连接但没有可用工具

故障排除：

  1. 验证工具注册： 确保你的服务器实际注册了工具
  2. 检查 MCP 协议： 确认你的服务器正确实现了 MCP 工具列表
  3. 查看服务器日志： 检查 stderr 输出中的服务器端错误
  4. 测试工具列表： 手动测试你的服务器的工具发现端点

重要说明 ​

安全考虑 ​

  • 信任设置： trust 选项绕过所有确认对话框。谨慎使用，仅用于你完全控制的服务器
  • 访问令牌： 配置包含 API 密钥或令牌的环境变量时要注意安全
  • 沙盒兼容性： 使用沙盒时，确保 MCP 服务器在沙盒环境中可用
  • 私有数据： 使用具有广泛权限范围的个人访问令牌可能导致仓库之间的信息泄露

性能和资源管理 ​

  • 持久连接： CLI 维护与成功注册工具的服务器的持久连接
  • 自动清理： 不提供工具的服务器的连接会自动关闭
  • 超时管理： 根据服务器的响应特性配置适当的超时
  • 资源监控： MCP 服务器作为单独的进程运行并消耗系统资源

MCP 提示作为斜杠命令 ​

除了工具之外，MCP 服务器还可以公开预定义的提示，这些提示可以作为 Gemini CLI 中的斜杠命令执行。这允许你为常见或复杂的查询创建快捷方式，可以通过名称轻松调用。

调用提示 ​

一旦发现提示，你可以使用其名称作为斜杠命令调用它。CLI 将自动处理参数解析。

bash
/poem-writer --title="Gemini CLI" --mood="reverent"

或者，使用位置参数：

bash
/poem-writer "Gemini CLI" reverent

使用 gemini mcp 管理 MCP 服务器 ​

虽然你始终可以通过手动编辑 settings.json 文件来配置 MCP 服务器，但 Gemini CLI 提供了一组方便的命令来以编程方式管理你的服务器配置。

添加服务器（gemini mcp add） ​

add 命令在你的 settings.json 中配置新的 MCP 服务器。

命令：

bash
gemini mcp add [options] <name> <commandOrUrl> [args...]
  • <name>：服务器的唯一名称。
  • <commandOrUrl>：要执行的命令（用于 stdio）或 URL（用于 http/sse）。
  • [args...]：stdio 命令的可选参数。

选项（标志）：

  • -s, --scope：配置范围（user 或 project）。[默认："project"]
  • -t, --transport：传输类型（stdio、sse、http）。[默认："stdio"]
  • -e, --env：设置环境变量（例如 -e KEY=value）。
  • -H, --header：为 SSE 和 HTTP 传输设置 HTTP 头。
  • --timeout：请求超时（毫秒）。

aicodex 文档网站

Copyright © 2025