使用 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、自定义脚本或特殊工作流程交互。

核心集成架构

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

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

发现过程由 discoverMcpTools() 组织，它：

遍历配置的服务器 从您的 settings.json mcpServers 配置
建立连接 使用适当的传输机制（Stdio、SSE 或流式 HTTP）
获取工具定义 使用 MCP 协议从每个服务器获取
清理和验证 工具架构与 Gemini API 的兼容性
注册工具 在全局工具注册表中，具有冲突解决
获取并注册资源 如果服务器公开了任何资源

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

每个发现的 MCP 工具都被包装在 DiscoveredMCPTool 实例中，它：

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

传输机制

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

标准I/O传输： 启动一个子进程并通过stdin/stdout进行通信
SSE传输： 连接到Server-Sent Events端点
流式HTTP传输： 使用HTTP流式通信

使用MCP资源

一些MCP服务器除了工具和提示外，还公开了上下文“资源”。Gemini CLI会自动发现这些资源，并允许您在聊天中引用它们。

发现和列出

当进行发现操作时，CLI会获取每个服务器的resources/list结果。
/mcp命令会在每个连接的服务器旁边显示工具和提示的资源部分。

这将返回一个简洁的纯文本URI列表以及元数据。

在对话中引用资源

您可以使用已知的本地文件引用语法@：

@server://resource/path

资源URI会与文件系统路径一起出现在补全菜单中。当您提交消息时，CLI会调用resources/read并将内容注入对话中。

如何设置您的MCP服务器

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

在settings.json中配置MCP服务器

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

全局MCP设置 (`mcp`)

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

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

示例：

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

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

在mcpServers对象中，您可以定义每个希望CLI连接的独立MCP服务器。

配置结构

在您的settings.json文件中添加一个mcpServers对象：

{ ...file contains other config objects
  "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

可选

…（此处原文未给出后续内容，故翻译亦到此为止）

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

对远程 MCP 服务器的 OAuth 支持

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

自动 OAuth 发现

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

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

CLI 将自动：

【翻译】

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

认证流程

连接到启用 OAuth 的服务器时：

初次连接尝试 失败，返回 401 未授权
OAuth 发现 找到授权和令牌端点
浏览器打开 进行用户认证（需要本地浏览器访问）
授权码 用于交换访问令牌
令牌安全存储 以供将来使用
重新连接尝试 使用有效令牌成功

浏览器重定向要求

重要： OAuth 认证要求您的本地机器能够：

打开网络浏览器进行认证
在 http://localhost:7777/oauth/callback 上接收重定向

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

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

管理 OAuth 认证

使用 /mcp auth 命令管理 OAuth 认证：

# List servers requiring authentication
/mcp auth

# Authenticate with a specific server
/mcp auth serverName

# Re-authenticate if tokens expire
/mcp auth serverName

OAuth 配置属性

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

令牌管理

OAuth 令牌会自动：

（注：由于原文最后一句未完成，翻译也相应地未完成。）

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

认证提供商类型

您可以使用authProviderType属性指定认证提供商类型：

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

Google凭据

{
  "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（字符串）：OAuth客户端ID，允许在您尝试访问的IAP保护应用程序上列出。
targetServiceAccount（字符串）：要模拟的Google云服务帐户的电子邮件地址。

CLI将使用您的本地应用程序默认凭据（ADC）为指定的服务帐户和受众生成OIDC ID令牌。然后此令牌将用于与MCP服务器进行认证。

设置说明

创建或使用现有的 OAuth 2.0 客户端 ID。 若要使用现有的 OAuth 2.0 客户端 ID，请按照如何共享OAuth客户端中的步骤操作。
将OAuth ID添加到应用程序的编程访问允许名单中。 由于Cloud Run在gcloud iap中尚不支持资源类型，您必须在项目上允许列出客户端ID。
创建一个服务账户。 文档，云控制台链接
将服务账户和用户都添加到IAP策略中，在Cloud Run服务的“安全”选项卡上直接操作，或者通过gcloud。
授予所有用户和组 访问MCP服务器所需的权限，以模拟服务账户（即，roles/iam.serviceAccountTokenCreator）。
启用 IAM凭据API 用于您的项目。

示例配置

Python MCP服务器（stdio）

{
  "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）

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

基于Docker的MCP服务器

{
  "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服务器

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

带有自定义头的HTTP-based MCP服务器

{
  "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服务器

{
  "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服务器

{
  "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 实现了复杂的确认逻辑：

基于信任的绕过

if (this.trust) {
  return false; // No confirmation needed
}

动态允许列表

系统维护以下内部允许列表：

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

用户选择处理

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

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

3. 执行

在确认（或信任绕过）后：

参数准备： 验证参数是否与工具架构相符

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

const functionCalls = [
  {
    name: this.serverToolName, // Original server tool name
    args: params,
  },
];

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

4. 响应处理

执行结果包含：

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

如何与您的 MCP 服务器交互

使用 `/mcp` 命令

/mcp 命令提供有关您的 MCP 服务器设置的综合信息：

/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工具清单。 查看服务器日志： 检查stderr输出以查找服务器端错误。 测试工具清单： 手动测试您的服务器的工具发现端点。

工具无法执行

症状： 工具被发现，但在执行过程中失败。

故障排除：

参数验证： 确保您的工具接受预期的参数。
架构兼容性： 验证您的输入架构是否为有效的JSON架构。
错误处理： 检查您的工具是否抛出了未处理的异常。
超时问题： 考虑增加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

示例：返回文本和图片

以下是一个有效的JSON响应示例，来自一个MCP工具，它同时返回文本描述和图片：

{
  "content": [
    {
      "type": "text",
      "text": "Here is the logo you requested."
    },
    {
      "type": "image",
      "data": "BASE64_ENCODED_IMAGE_DATA_HERE",
      "mimeType": "image/png"
    },
    {
      "type": "text",
      "text": "The logo was created in 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 中，方法是：

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

调用提示

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

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

或者，使用位置参数：

/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 中。

命令：

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

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

选项（标志）：

【配置范围】

-s, --scope: 配置范围（用户或项目）。[默认: “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服务器

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

# Basic syntax
gemini mcp add [options] <name> <command> [args...]

# Example: Adding a local server
gemini mcp add -e API_KEY=123 -e DEBUG=true my-stdio-server /path/to/server arg1 arg2 arg3

# Example: Adding a local python server
gemini mcp add python-server python server.py -- --server-arg my-value

添加HTTP服务器

这种传输方式适用于使用流式HTTP传输的服务器。

# Basic syntax
gemini mcp add --transport http <name> <url>

# Example: Adding an HTTP server
gemini mcp add --transport http http-server https://api.example.com/mcp/

# Example: Adding an HTTP server with an authentication header
gemini mcp add --transport http --header "Authorization: Bearer abc123" secure-http https://api.example.com/mcp/

添加SSE服务器

这种传输方式适用于使用服务器发送事件（SSE）的服务器。

# Basic syntax
gemini mcp add --transport sse <name> <url>

# Example: Adding an SSE server
gemini mcp add --transport sse sse-server https://api.example.com/sse/

# Example: Adding an SSE server with an authentication header
gemini mcp add --transport sse --header "Authorization: Bearer abc123" secure-sse https://api.example.com/sse/

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

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

命令：

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命令和服务器名称。

命令：

gemini mcp remove <name>

选项（标志）：

-s, --scope: 配置范围（用户或项目）。[默认: “project”]

示例：

gemini mcp remove my-server

这将根据范围（-s, --scope）在相应的settings.json文件中找到并删除”my-server”条目。

说明

【操作指南】

Gemini CLI 支持 MCP 服务器指令，这些指令将被附加到系统指令中。

使用 Gemini CLI 的 MCP 服务器

使用 Gemini CLI 的 MCP 服务器

什么是 MCP 服务器？

核心集成架构

发现层 (mcp-client.ts)

执行层 (mcp-tool.ts)

传输机制

使用MCP资源

发现和列出

在对话中引用资源

如何设置您的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-based 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服务器

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

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

全局MCP设置 (`mcp`)

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

使用 `/mcp` 命令

示例 `/mcp` 输出

服务器状态 (`MCPServerStatus`)

发现状态 (`MCPDiscoveryState`)

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

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

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

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