MCP 服务器与 Gemini CLI

本文档提供了使用 Gemini CLI 配置和使用模型上下文协议 (MCP) 服务器的指南。

什么是 MCP 服务器？

MCP 服务器是一种应用程序，它通过模型上下文协议 (Model Context Protocol) 将工具和资源暴露给 Gemini CLI，使其能够与外部系统和数据源进行交互。MCP 服务器充当 Gemini 模型与您的本地环境或其他服务（如 API）之间的桥梁。

MCP 服务器使 Gemini CLI 能够：

发现工具： 通过标准化的模式定义列出可用的工具、它们的描述和参数。
执行工具： 使用定义的参数调用特定工具并接收结构化响应。
访问资源： 从特定资源读取数据（尽管 Gemini CLI 主要关注工具执行）。

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

核心集成架构

Gemini CLI 通过内置的核心包 (packages/core/src/tools/) 中的复杂发现和执行系统与 MCP 服务器集成：

发现层 (`mcp-client.ts`)

发现过程由 discoverMcpTools() 协调，该函数：

遍历 settings.json mcpServers 配置中定义的服务器。
建立连接，使用适当的传输机制（Stdio、SSE 或 Streamable HTTP）。
从每个服务器获取工具定义，使用 MCP 协议。
清理和验证工具模式，以确保与 Gemini API 的兼容性。
在全局工具注册表中注册工具，并进行冲突解决。

执行层 (`mcp-tool.ts`)

每个发现的 MCP 工具都封装在 DiscoveredMCPTool 实例中，该实例：

处理确认逻辑，基于服务器信任设置和用户偏好。
管理工具执行，通过调用 MCP 服务器并传递正确的参数。
处理响应，用于 LLM 上下文和用户显示。
维护连接状态并处理超时。

传输机制

Gemini CLI 支持三种 MCP 传输类型：

Stdio 传输： 启动一个子进程并通过 stdin/stdout 进行通信。
SSE 传输： 连接到服务器发送事件 (Server-Sent Events) 端点。
Streamable HTTP 传输： 使用 HTTP 流进行通信。

如何设置您的 MCP 服务器

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

在 settings.json 中配置 MCP 服务器

您可以通过两种主要方式在 settings.json 文件中配置 MCP 服务器：通过顶级的 mcpServers 对象进行特定服务器定义，以及通过 mcp 对象进行全局设置，以控制服务器发现和执行。

全局 MCP 设置 (`mcp`)

settings.json 中的 mcp 对象允许您为所有 MCP 服务器定义全局规则。

mcp.serverCommand (string)：启动 MCP 服务器的全局命令。
mcp.allowed (string 数组)：允许的 MCP 服务器名称列表。如果设置了此项，则只连接此列表中的服务器（匹配 mcpServers 对象中的键）。
mcp.excluded (string 数组)：要排除的 MCP 服务器名称列表。此列表中的服务器将不会被连接。

示例：

json

{
  "mcp": {
    "allowed": ["my-trusted-server"],
    "excluded": ["experimental-server"]
  }
}

特定服务器配置 (`mcpServers`)

mcpServers 对象是定义您希望 CLI 连接的每个 MCP 服务器的地方。

配置结构

将 mcpServers 对象添加到您的 settings.json 文件：

json

{ ...文件包含其他配置对象
  "mcpServers": {
    "serverName": {
      "command": "path/to/server",
      "args": ["--arg1", "value1"],
      "env": {
        "API_KEY": "$MY_API_TOKEN"
      },
      "cwd": "./server-directory",
      "timeout": 30000,
      "trust": false
    }
  }
}

配置属性

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

必需（以下之一）

command (string)：Stdio 传输的可执行文件路径。
url (string)：SSE 端点 URL（例如 "http://localhost:8080/sse"）。
httpUrl (string)：HTTP 流式传输端点 URL。

可选

args (string[])：Stdio 传输的命令行参数。
headers (object)：使用 url 或 httpUrl 时的自定义 HTTP 标头。
env (object)：服务器进程的环境变量。值可以使用 $VAR_NAME 或 ${VAR_NAME} 语法引用环境变量。
cwd (string)：Stdio 传输的工作目录。
timeout (number)：请求超时（以毫秒为单位，默认值：600,000 毫秒 = 10 分钟）。
trust (boolean)：如果为 true，则绕过此服务器的所有工具调用确认（默认值：false）。
includeTools (string[])：从此 MCP 服务器包含的工具名称列表。如果指定，则只有此处列出的工具可从此服务器获得（允许列表行为）。如果未指定，则默认启用服务器的所有工具。
excludeTools (string[])：从此 MCP 服务器排除的工具名称列表。此处列出的工具将不可供模型使用，即使它们由服务器公开。注意： excludeTools 优先于 includeTools - 如果一个工具同时出现在两个列表中，它将被排除。
targetAudience (string)：您正在访问的 IAP 保护应用程序上允许列表中的 OAuth 客户端 ID。与 authProviderType: 'service_account_impersonation' 一起使用。
targetServiceAccount (string)：要模拟的 Google Cloud 服务帐户的电子邮件地址。与 authProviderType: 'service_account_impersonation' 一起使用。

远程 MCP 服务器的 OAuth 支持

Gemini CLI 支持使用 SSE 或 HTTP 传输的远程 MCP 服务器的 OAuth 2.0 身份验证。这使得可以安全地访问需要身份验证的 MCP 服务器。

自动 OAuth 发现

对于支持 OAuth 发现的服务器，您可以省略 OAuth 配置，让 CLI 自动发现它：

json

{
  "mcpServers": {
    "discoveredServer": {
      "url": "https://api.example.com/sse"
    }
  }
}

CLI 将自动：

检测服务器何时需要 OAuth 身份验证（401 响应）。
从服务器元数据发现 OAuth 端点。
如果支持，则执行动态客户端注册。
处理 OAuth 流程和令牌管理。

身份验证流程

连接到支持 OAuth 的服务器时：

首次连接尝试失败并显示 401 Unauthorized。
OAuth 发现找到授权和令牌端点。
浏览器打开以进行用户身份验证（需要本地浏览器访问）。
授权码被交换为访问令牌。
令牌被安全存储以供将来使用。
连接重试成功，并带有有效令牌。

浏览器重定向要求

重要提示： OAuth 身份验证要求您的本地计算机能够：

打开 Web 浏览器进行身份验证。
在 http://localhost:7777/oauth/callback 上接收重定向。

此功能将无法在以下环境中工作：

没有浏览器访问权限的无头环境。
没有 X11 转发的远程 SSH 会话。
没有浏览器支持的容器化环境。

管理 OAuth 身份验证

使用 /mcp auth 命令管理 OAuth 身份验证：

bash

# 列出需要身份验证的服务器
/mcp auth

# 使用特定服务器进行身份验证
/mcp auth serverName

# 如果令牌过期，请重新进行身份验证
/mcp auth serverName

OAuth 配置属性

enabled (boolean)：为此服务器启用 OAuth。
clientId (string)：OAuth 客户端标识符（使用动态注册时可选）。
clientSecret (string)：OAuth 客户端密钥（对于公共客户端可选）。
authorizationUrl (string)：OAuth 授权端点（如果省略则自动发现）。
tokenUrl (string)：OAuth 令牌端点（如果省略则自动发现）。
scopes (string[])：必需的 OAuth 范围。
redirectUri (string)：自定义重定向 URI（默认为 http://localhost:7777/oauth/callback）。
tokenParamName (string)：SSE URL 中令牌的查询参数名称。
audiences (string[])：令牌有效的受众。

令牌管理

OAuth 令牌会自动：

安全地存储在 ~/.gemini/mcp-oauth-tokens.json 中。
在过期时刷新（如果存在刷新令牌）。
在每次连接尝试之前进行验证。
在无效或过期时清理。

身份验证提供程序类型

您可以使用 authProviderType 属性指定身份验证提供程序类型：

authProviderType (string)：指定身份验证提供程序。可以是以下之一：
- dynamic_discovery (默认)：CLI 将自动从服务器发现 OAuth 配置。
- google_credentials：CLI 将使用 Google 应用程序默认凭据 (ADC) 进行服务器身份验证。使用此提供程序时，必须指定必需的范围。
- service_account_impersonation：CLI 将模拟 Google Cloud 服务帐户以进行服务器身份验证。这对于访问 IAP 保护的服务很有用（这是专门为 Cloud Run 服务设计的）。

Google 凭据

json

{
  "mcpServers": {
    "googleCloudServer": {
      "httpUrl": "https://my-gcp-service.run.app/mcp",
      "authProviderType": "google_credentials",
      "oauth": {
        "scopes": ["https://www.googleapis.com/auth/userinfo.email"]
      }
    }
  }
}

服务帐户模拟

要使用服务帐户模拟进行服务器身份验证，您必须将 authProviderType 设置为 service_account_impersonation 并提供以下属性：

targetAudience (string)：您正在访问的 IAP 保护应用程序上允许列表中的 OAuth 客户端 ID。
targetServiceAccount (string)：要模拟的 Google Cloud 服务帐户的电子邮件地址。

CLI 将使用您的本地应用程序默认凭据 (ADC) 为指定的服务帐户和受众生成 OIDC ID 令牌。然后，该令牌将用于向 MCP 服务器进行身份验证。

设置说明

创建或使用现有的 OAuth 2.0 客户端 ID。 要使用现有的 OAuth 2.0 客户端 ID，请遵循如何共享 OAuth 客户端中的步骤。
将 OAuth ID 添加到应用程序以进行编程访问的允许列表中。 由于 Cloud Run 尚未成为 gcloud iap 中的受支持资源类型，因此您必须在项目上允许客户端 ID。
创建服务帐户。 文档, Cloud Console 链接
将服务帐户和用户添加到 IAP 策略，在 Cloud Run 服务本身的“安全”选项卡中或通过 gcloud。
授予所有将访问 MCP 服务器的用户和组必要的权限以模拟服务帐户（即 roles/iam.serviceAccountTokenCreator）。
为您的项目启用 IAM Credentials API。

示例配置

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",
        "API_KEY": "${EXTERNAL_API_KEY}"
      },
      "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
    }
  }
}

具有自定义标头的基于 HTTP 的 MCP 服务器

json

{
  "mcpServers": {
    "httpServerWithAuth": {
      "httpUrl": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-api-token",
        "X-Custom-Header": "custom-value",
        "Content-Type": "application/json"
      },
      "timeout": 5000
    }
  }
}

具有工具过滤的 MCP 服务器

json

{
  "mcpServers": {
    "filteredServer": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "includeTools": ["safe_tool", "file_reader", "data_processor"],
      // "excludeTools": ["dangerous_tool", "file_deleter"],
      "timeout": 30000
    }
  }
}

具有 SA 模拟的 SSE MCP 服务器

json

{
  "mcpServers": {
    "myIapProtectedServer": {
      "url": "https://my-iap-service.run.app/sse",
      "authProviderType": "service_account_impersonation",
      "targetAudience": "YOUR_IAP_CLIENT_ID.apps.googleusercontent.com",
      "targetServiceAccount": "your-sa@your-project.iam.gserviceaccount.com"
    }
  }
}

发现过程深入分析

当 Gemini CLI 启动时，它会通过以下详细过程执行 MCP 服务器发现：

1. 服务器迭代和连接

对于 mcpServers 中的每个配置的服务器：

开始状态跟踪： 服务器状态设置为 CONNECTING。
传输选择： 基于配置属性：
- httpUrl → StreamableHTTPClientTransport
- url → SSEClientTransport
- command → StdioClientTransport
建立连接： MCP 客户端尝试使用配置的超时进行连接。
错误处理： 连接失败会被记录，服务器状态设置为 DISCONNECTED。

2. 工具发现

成功连接后：

工具列表： 客户端调用 MCP 服务器的工具列表端点。
模式验证： 每个工具的函数声明都会得到验证。
工具过滤： 根据 includeTools 和 excludeTools 配置过滤工具。
名称清理： 工具名称会被清理，以满足 Gemini API 的要求：
- 无效字符（非字母数字、下划线、点、连字符）会被替换为下划线。
- 长度超过 63 个字符的名称会被截断并进行中间替换 (___)。

3. 冲突解决

当多个服务器公开同名工具时：

先注册者获胜： 第一个注册工具名称的服务器获得未加前缀的名称。
自动加前缀： 后续服务器获得加前缀的名称：serverName__toolName。
注册表跟踪： 工具注册表维护服务器名称与其工具之间的映射。

4. 模式处理

工具参数模式会经过清理，以确保与 Gemini API 的兼容性：

$schema 属性会被移除。
additionalProperties 会被剥离。
anyOf 与 default 的默认值会被移除（Vertex AI 兼容性）。
递归处理应用于嵌套模式。

5. 连接管理

发现后：

持久连接： 成功注册工具的服务器会保持其连接。
清理： 提供无可用工具的服务器的连接会被自动关闭。
状态更新： 最终服务器状态设置为 CONNECTED 或 DISCONNECTED。

工具执行流程

当 Gemini 模型决定使用 MCP 工具时，会发生以下执行流程：

1. 工具调用

模型生成一个 FunctionCall，包含：

工具名称： 注册的名称（可能已加前缀）。
参数： 符合工具参数模式的 JSON 对象。

2. 确认过程

每个 DiscoveredMCPTool 都实现了复杂的确认逻辑：

基于信任的绕过

typescript

if (this.trust) {
  return false; // 无需确认
}

动态允许列表

系统维护内部允许列表：

服务器级别： serverName → 此服务器的所有工具都受信任。
工具级别： serverName.toolName → 此特定工具受信任。

用户选择处理

当需要确认时，用户可以选择：

仅此一次继续： 只执行这一次。
始终允许此工具： 添加到工具级别允许列表。
始终允许此服务器： 添加到服务器级别允许列表。
取消： 中止执行。

3. 执行

确认后（或信任绕过）：

参数准备： 参数会根据工具的模式进行验证。

MCP 调用： 底层的 CallableTool 使用以下内容调用服务器：

typescript

const functionCalls = [
  {
    name: this.serverToolName, // 原始服务器工具名称
    args: params,
  },
];

响应处理： 结果会为 LLM 上下文和用户显示进行格式化。

4. 响应处理

执行结果包含：

llmContent： 语言模型上下文的原始响应部分。
returnDisplay： 用于用户显示的格式化输出（通常是 markdown 代码块中的 JSON）。

如何与您的 MCP 服务器交互

使用 `/mcp` 命令

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

bash

/mcp

这将显示：

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

示例 `/mcp` 输出

MCP Servers Status:

📡 pythonTools (CONNECTED)
  Command: python -m my_mcp_server --port 8080
  Working Directory: ./mcp-servers/python
  Timeout: 15000ms
  Tools: calculate_sum, file_analyzer, data_processor

🔌 nodeServer (DISCONNECTED)
  Command: node dist/server.js --verbose
  Error: Connection refused

🐳 dockerizedServer (CONNECTED)
  Command: docker run -i --rm -e API_KEY my-mcp-server:latest
  Tools: docker__deploy, docker__status

Discovery State: COMPLETED

工具使用

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

选择合适的工具，根据您的请求。
显示确认对话框（除非服务器受信任）。
执行工具，并使用正确的参数。
以用户友好的格式显示结果。

状态监控和故障排除

连接状态

MCP 集成跟踪多种状态：

服务器状态 (`MCPServerStatus`)

DISCONNECTED： 服务器未连接或存在错误。
CONNECTING： 正在尝试连接。
CONNECTED： 服务器已连接并准备就绪。

发现状态 (`MCPDiscoveryState`)

NOT_STARTED： 发现尚未开始。
IN_PROGRESS： 正在进行发现。
COMPLETED： 发现已完成（无论是否有错误）。

常见问题和解决方案

服务器无法连接

症状： 服务器显示 DISCONNECTED 状态。

故障排除：

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

未发现任何工具

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

故障排除：

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

工具执行失败

症状： 工具已发现但执行失败。

故障排除：

参数验证： 确保您的工具接受预期的参数。
模式兼容性： 验证您的输入模式是否为有效的 JSON Schema。
错误处理： 检查您的工具是否抛出了未处理的异常。
超时问题： 考虑增加 timeout 设置。

沙盒兼容性

症状： 启用沙盒时 MCP 服务器失败。

解决方案：

基于 Docker 的服务器： 使用包含所有依赖项的 Docker 容器。
路径可访问性： 确保沙盒中存在服务器可执行文件。
网络访问： 配置沙盒以允许必要的网络连接。
环境变量： 验证所需的环境变量是否已传递。

调试技巧

启用调试模式： 使用 --debug 运行 CLI 以获取详细输出。
检查 stderr： MCP 服务器的 stderr 会被捕获并记录（INFO 消息被过滤）。
隔离测试： 在集成之前独立测试您的 MCP 服务器。
增量设置： 在添加复杂功能之前，从简单的工具开始。
频繁使用 /mcp： 在开发过程中监控服务器状态。

重要说明

安全注意事项

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

性能和资源管理

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

模式兼容性

属性剥离： 系统会自动移除某些模式属性（$schema、additionalProperties）以确保 Gemini API 兼容性。
名称清理： 工具名称会自动清理以满足 API 要求。
冲突解决： 服务器之间的工具名称冲突会通过自动加前缀来解决。

这种全面的集成使得 MCP 服务器成为扩展 Gemini CLI 功能的强大方式，同时保持安全性、可靠性和易用性。

从工具返回丰富内容

MCP 工具不仅限于返回简单的文本。您可以在一次工具响应中返回丰富的多部分内容，包括文本、图像、音频和其他二进制数据。这使您能够构建强大的工具，一次性向模型提供多样化的信息。

从工具返回的所有数据都会被处理并作为上下文发送给模型进行下一次生成，使模型能够对其进行推理或总结。

工作原理

要返回丰富内容，您的工具响应必须符合 MCP 规范的 CallToolResult。结果的 content 字段应为 ContentBlock 对象数组。Gemini CLI 将正确处理此数组，将文本与二进制数据分开，并将其打包供模型使用。

您可以在 content 数组中混合搭配不同的内容块类型。支持的内容块类型包括：

text
image
audio
resource（嵌入式内容）
resource_link

示例：返回文本和图像

以下是一个 MCP 工具返回文本描述和图像的有效 JSON 响应示例：

json

{
  "content": [
    {
      "type": "text",
      "text": "这是您要求的徽标。"
    },
    {
      "type": "image",
      "data": "BASE64_ENCODED_IMAGE_DATA_HERE",
      "mimeType": "image/png"
    },
    {
      "type": "text",
      "text": "该徽标创建于 2025 年。"
    }
  ]
}

当 Gemini CLI 收到此响应时，它将：

提取所有文本，并将它们合并为模型的一个 functionResponse 部分。
将图像数据作为单独的 inlineData 部分呈现。
在 CLI 中提供一个清晰、用户友好的摘要，表明已收到文本和图像。

这使您能够构建复杂的工具，为 Gemini 模型提供丰富的多模态上下文。

MCP 提示作为斜杠命令

除了工具之外，MCP 服务器还可以公开预定义的提示，这些提示可以在 Gemini CLI 中作为斜杠命令执行。这使您能够为常用或复杂的查询创建快捷方式，并可以轻松地按名称调用它们。

在服务器上定义提示

这是一个定义提示的简单 stdio MCP 服务器示例：

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

const server = new McpServer({
  name: 'prompt-server',
  version: '1.0.0',
});

server.registerPrompt(
  'poem-writer',
  {
    title: 'Poem Writer',
    description: 'Write a nice haiku',
    argsSchema: { title: z.string(), mood: z.string().optional() },
  },
  ({ title, mood }) => ({
    messages: [
      {
        role: 'user',
        content: {
          type: 'text',
          text: `Write a haiku${mood ? ` with the mood ${mood}` : ''} called ${title}. Note that a haiku is 5 syllables followed by 7 syllables followed by 5 syllables `,
        },
      },
    ],
  }),
);

const transport = new StdioServerTransport();
await server.connect(transport);

可以在 settings.json 的 mcpServers 下包含此内容：

json

{
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["filename.ts"]
    }
  }
}

调用提示

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

bash

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

或者，使用位置参数：

bash

/poem-writer "Gemini CLI" reverent

运行此命令时，Gemini CLI 会使用提供的参数在 MCP 服务器上执行 prompts/get 方法。服务器负责将参数替换到提示模板中并返回最终的提示文本。然后，CLI 将此提示发送给模型执行。这提供了一种自动化和共享常用工作流的便捷方式。

使用 `gemini mcp` 管理 MCP 服务器

虽然您始终可以通过直接编辑 settings.json 文件来配置 MCP 服务器，但 Gemini CLI 提供了一组方便的命令来以编程方式管理您的服务器配置。这些命令简化了添加、列出和删除 MCP 服务器的过程，而无需直接编辑 JSON 文件。

添加服务器 (`gemini mcp add`)

add 命令会在您的 settings.json 中配置一个新的 MCP 服务器。根据范围 (-s, --scope)，它将被添加到用户配置文件 ~/.gemini/settings.json 或项目配置文件 .gemini/settings.json 文件中。

命令：

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 标头（例如 -H "X-Api-Key: abc123" -H "Authorization: Bearer abc123"）。
--timeout：设置连接超时（以毫秒为单位）。
--trust：信任服务器（绕过所有工具调用确认提示）。
--description：设置服务器的描述。
--include-tools：逗号分隔的工具列表。
--exclude-tools：逗号分隔的工具列表。

添加 stdio 服务器

这是运行本地服务器的默认传输。

bash

# 基本语法
gemini mcp add <name> <command> [args...]

# 示例：添加本地服务器
gemini mcp add my-stdio-server -e API_KEY=123 /path/to/server arg1 arg2 arg3

# 示例：添加本地 Python 服务器
gemini mcp add python-server python server.py --port 8080

添加 HTTP 服务器

此传输用于使用流式 HTTP 传输的服务器。

bash

# 基本语法
gemini mcp add --transport http <name> <url>

# 示例：添加 HTTP 服务器
gemini mcp add --transport http http-server https://api.example.com/mcp/

# 示例：添加带有身份验证标头的 HTTP 服务器
gemini mcp add --transport http secure-http https://api.example.com/mcp/ --header "Authorization: Bearer abc123"

添加 SSE 服务器

此传输用于使用服务器发送事件 (SSE) 的服务器。

bash

# 基本语法
gemini mcp add --transport sse <name> <url>

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

# 示例：添加带有身份验证标头的 SSE 服务器
gemini mcp add --transport sse secure-sse https://api.example.com/sse/ --header "Authorization: Bearer abc123"

列出服务器 (`gemini mcp list`)

要查看当前配置的所有 MCP 服务器，请使用 list 命令。它会显示每个服务器的名称、配置详细信息和连接状态。

命令：

bash

gemini mcp list

示例输出：

✓ stdio-server: command: python3 server.py (stdio) - Connected
✓ http-server: https://api.example.com/mcp (http) - Connected
✗ sse-server: https://api.example.com/sse (sse) - Disconnected

删除服务器 (`gemini mcp remove`)

要从您的配置中删除服务器，请使用服务器名称的 remove 命令。

命令：

bash

gemini mcp remove <name>

示例：

bash

gemini mcp remove my-server

这将根据范围 (-s, --scope) 在适当的 settings.json 文件中查找并删除 mcpServers 对象中的 "my-server" 条目。

MCP 服务器与 Gemini CLI ​

什么是 MCP 服务器？ ​

核心集成架构 ​

发现层 (mcp-client.ts) ​

执行层 (mcp-tool.ts) ​

传输机制 ​

如何设置您的 MCP 服务器 ​

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

全局 MCP 设置 (mcp) ​

特定服务器配置 (mcpServers) ​

配置结构 ​

配置属性 ​

必需（以下之一） ​

可选 ​

远程 MCP 服务器的 OAuth 支持 ​

自动 OAuth 发现 ​

身份验证流程 ​

浏览器重定向要求 ​

管理 OAuth 身份验证 ​

OAuth 配置属性 ​

令牌管理 ​

身份验证提供程序类型 ​

Google 凭据 ​

服务帐户模拟 ​

设置说明 ​

示例配置 ​

Python MCP 服务器 (Stdio) ​

Node.js MCP 服务器 (Stdio) ​

基于 Docker 的 MCP 服务器 ​

基于 HTTP 的 MCP 服务器 ​

具有自定义标头的基于 HTTP 的 MCP 服务器 ​

具有工具过滤的 MCP 服务器 ​

具有 SA 模拟的 SSE MCP 服务器 ​

发现过程深入分析 ​

1. 服务器迭代和连接 ​

2. 工具发现 ​

3. 冲突解决 ​

4. 模式处理 ​

5. 连接管理 ​

工具执行流程 ​

1. 工具调用 ​

2. 确认过程 ​

基于信任的绕过 ​

动态允许列表 ​

用户选择处理 ​

3. 执行 ​

4. 响应处理 ​

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

使用 /mcp 命令 ​

示例 /mcp 输出 ​

工具使用 ​

状态监控和故障排除 ​

连接状态 ​

服务器状态 (MCPServerStatus) ​

发现状态 (MCPDiscoveryState) ​

常见问题和解决方案 ​

服务器无法连接 ​

未发现任何工具 ​

工具执行失败 ​

沙盒兼容性 ​

调试技巧 ​

重要说明 ​

安全注意事项 ​

性能和资源管理 ​

模式兼容性 ​

从工具返回丰富内容 ​

工作原理 ​

示例：返回文本和图像 ​

MCP 提示作为斜杠命令 ​

在服务器上定义提示 ​

调用提示 ​

使用 gemini mcp 管理 MCP 服务器 ​

添加服务器 (gemini mcp add) ​

添加 stdio 服务器 ​

添加 HTTP 服务器 ​

添加 SSE 服务器 ​

列出服务器 (gemini mcp list) ​

删除服务器 (gemini mcp remove) ​

MCP 服务器与 Gemini CLI

什么是 MCP 服务器？

核心集成架构

发现层 (`mcp-client.ts`)

执行层 (`mcp-tool.ts`)

传输机制

如何设置您的 MCP 服务器

在 settings.json 中配置 MCP 服务器

全局 MCP 设置 (`mcp`)

特定服务器配置 (`mcpServers`)

配置结构

配置属性

必需（以下之一）

可选

远程 MCP 服务器的 OAuth 支持

自动 OAuth 发现

身份验证流程

浏览器重定向要求

管理 OAuth 身份验证

OAuth 配置属性

令牌管理

身份验证提供程序类型

Google 凭据

服务帐户模拟

设置说明

示例配置

Python MCP 服务器 (Stdio)

Node.js MCP 服务器 (Stdio)

基于 Docker 的 MCP 服务器

基于 HTTP 的 MCP 服务器

具有自定义标头的基于 HTTP 的 MCP 服务器

具有工具过滤的 MCP 服务器

具有 SA 模拟的 SSE MCP 服务器

发现过程深入分析

1. 服务器迭代和连接

2. 工具发现

3. 冲突解决

4. 模式处理

5. 连接管理

工具执行流程

1. 工具调用

2. 确认过程

基于信任的绕过

动态允许列表

用户选择处理

3. 执行

4. 响应处理

如何与您的 MCP 服务器交互

使用 `/mcp` 命令

示例 `/mcp` 输出

工具使用

状态监控和故障排除

连接状态

服务器状态 (`MCPServerStatus`)

发现状态 (`MCPDiscoveryState`)

常见问题和解决方案

服务器无法连接

未发现任何工具

工具执行失败

沙盒兼容性

调试技巧

重要说明

安全注意事项

性能和资源管理

模式兼容性

从工具返回丰富内容

工作原理

示例：返回文本和图像

MCP 提示作为斜杠命令

在服务器上定义提示

调用提示

使用 `gemini mcp` 管理 MCP 服务器

添加服务器 (`gemini mcp add`)

添加 stdio 服务器

添加 HTTP 服务器

添加 SSE 服务器

列出服务器 (`gemini mcp list`)

删除服务器 (`gemini mcp remove`)