Gemini CLI 通过 MCP（Model Context Protocol）将外部服务的工具能力注入模型。本文是完整技术参考，覆盖三种传输方式的配置方法、所有配置字段含义、OAuth 2.0 远程认证、工具命名规范、富内容响应格式，以及 gemini mcp 系列管理命令——配置 MCP 时遇到问题，优先查本文。

MCP 服务器完整参考

MCP（Model Context Protocol）是 Gemini CLI 的能力扩展标准，通过 MCP 可以将任意外部服务（数据库、GitHub、Slack 等）的工具接入模型，让 AI 直接操作你的业务系统。

入门教程见接入 MCP 服务器（GitHub 示例），Extensions 打包方式见扩展插件（Extensions）。

架构概览

MCP 集成分为两层：

Discovery Layer（发现层）：Gemini CLI 启动时自动发现并连接所有配置的 MCP 服务器，获取每个服务器提供的工具列表，建立工具到服务器的映射。

Execution Layer（执行层）：模型需要调用某工具时，CLI 将请求路由到对应的 MCP 服务器进程，处理参数校验、确认对话框、权限检查，然后返回结果给模型。

传输方式

Stdio（标准输入输出）

最常用的传输方式，适合本地服务器：

json

{
  "mcpServers": {
    "myServer": {
      "command": "node",
      "args": ["server.js"],
      "cwd": "./mcp-servers"
    }
  }
}

CLI 以子进程方式启动服务器，通过 stdin/stdout 通信。

SSE（Server-Sent Events）

连接远程 SSE 端点：

json

{
  "mcpServers": {
    "remoteServer": {
      "url": "https://api.example.com/sse/",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

Streamable HTTP

连接支持流式 HTTP 的远程服务器：

json

{
  "mcpServers": {
    "httpServer": {
      "httpUrl": "https://api.example.com/mcp/",
      "headers": {
        "X-Api-Key": "${API_KEY}"
      }
    }
  }
}

完整配置字段参考

json

{
  "mcpServers": {
    "<server-name>": {
      "command": "...",
      "url": "...",
      "httpUrl": "...",
      "args": [],
      "cwd": "...",
      "env": {},
      "headers": {},
      "timeout": 10000,
      "trust": false,
      "includeTools": [],
      "excludeTools": [],
      "description": "..."
    }
  }
}

字段	类型	说明
`command`	string	Stdio 传输：启动服务器的可执行文件
`url`	string	SSE 传输：远程端点 URL
`httpUrl`	string	HTTP 传输：远程端点 URL
`args`	string[]	传给 `command` 的参数数组
`cwd`	string	服务器工作目录（默认当前目录）
`env`	object	注入服务器进程的环境变量（支持 `${VAR}` 引用）
`headers`	object	HTTP 请求头（SSE/HTTP 传输）
`timeout`	number	连接超时（毫秒，默认 10000）
`trust`	boolean	`true` 时跳过所有工具调用确认弹窗
`includeTools`	string[]	工具白名单（只启用列出的工具）
`excludeTools`	string[]	工具黑名单（禁用列出的工具）
`description`	string	服务器描述，显示在 `/mcp` 输出中

环境变量展开

env 字段中的值支持三种展开语法，均在 CLI 启动时从当前进程环境变量读取：

json

{
  "env": {
    "GITHUB_TOKEN": "${GITHUB_TOKEN}",
    "API_KEY": "$MY_API_KEY",
    "WINVAR": "%MY_WINDOWS_VAR%"
  }
}

字面量值（无 $ 或 %）直接传入，不做展开。

环境变量脱敏

CLI 内置安全过滤：名称中含 KEY、TOKEN、SECRET、PASSWORD、CREDENTIAL 等模式的环境变量，默认不会注入 Hook 进程（防止意外泄露）。

如需在 MCP 服务器中使用这类变量，在 settings.json 的 security.environmentVariableRedaction.allowed 中明确列出：

json

{
  "security": {
    "environmentVariableRedaction": {
      "enabled": true,
      "allowed": ["GITHUB_TOKEN", "MY_SERVICE_API_KEY"]
    }
  }
}

OAuth 认证（远程服务器）

远程 MCP 服务器（SSE/HTTP）可能要求 OAuth 2.0 认证。CLI 支持三种 OAuth 模式，通过 /mcp auth 命令触发。

dynamic_discovery

CLI 自动读取服务器的 .well-known 端点获取授权 URL，适合大多数公共 MCP 服务：

bash

/mcp auth my-remote-server

浏览器打开授权页，完成授权后 CLI 自动获取并存储 token。

google_credentials

使用 Google Application Default Credentials（ADC）认证，适合 Google Cloud 托管的 MCP 服务：

json

{
  "mcpServers": {
    "google-service": {
      "httpUrl": "https://my-service.run.app/mcp/",
      "authType": "google_credentials"
    }
  }
}

service_account_impersonation

通过服务账号模拟（Workload Identity）认证，适合企业 GCP 环境：

json

{
  "mcpServers": {
    "iap-protected": {
      "httpUrl": "https://internal.example.com/mcp/",
      "authType": "service_account_impersonation",
      "serviceAccountEmail": "sa@my-project.iam.gserviceaccount.com"
    }
  }
}

工具命名规范

MCP 工具使用完全限定名（FQN）格式：

mcp_{serverName}_{toolName}

例如：

服务器 github，工具 list_pull_requests → mcp_github_list_pull_requests
服务器 dockerizedServer，工具 docker_deploy → mcp_dockerizedServer_docker_deploy

如果不同服务器的工具名冲突，CLI 自动添加服务器名前缀。工具名中的特殊字符会被自动清理以满足 API 要求。

工具过滤

json

{
  "mcpServers": {
    "github": {
      "command": "npx -y @modelcontextprotocol/server-github",
      "includeTools": ["list_pull_requests", "create_issue"],
      "excludeTools": ["delete_repository"]
    }
  }
}

合并规则（适用于覆盖扩展配置时）：

excludeTools：取并集——任意来源排除的工具均被禁用
includeTools：取交集——只有双方白名单的交集才启用
excludeTools 优先级高于 includeTools

工具执行流程

确认机制

默认情况下，模型调用 MCP 工具前会显示确认弹窗，展示工具名和参数。用户可选：

确认执行：工具调用继续
拒绝：工具调用取消，模型收到拒绝通知
总是允许：本次会话内不再弹窗

设置 "trust": true 可完全跳过确认，仅适用于你完全控制的本地服务器。

工具结果处理

工具返回的结果由 CLI 处理后作为上下文发送给模型，模型基于此继续生成响应。

富内容返回

MCP 工具不限于返回纯文本，支持混合内容（文本 + 图像 + 音频等）：

json

{
  "content": [
    {
      "type": "text",
      "text": "分析结果如下。"
    },
    {
      "type": "image",
      "data": "BASE64_ENCODED_IMAGE_DATA",
      "mimeType": "image/png"
    },
    {
      "type": "text",
      "text": "图表说明：Y轴为请求数，X轴为时间。"
    }
  ]
}

支持的内容类型：text、image、audio、resource（嵌入内容）、resource_link

CLI 处理方式：

将所有文本合并为 functionResponse 部分发送给模型
将二进制数据作为独立的 inlineData 部分发送
在终端显示友好摘要，告知用户收到了哪些类型的内容

MCP Prompts 作为斜线命令

MCP 服务器除工具外，还可以暴露预定义 Prompts，CLI 自动将其映射为斜线命令。

服务器端定义示例

typescript

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}.`,
      },
    }],
  }),
);

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

调用方式

bash

# 命名参数
/poem-writer --title="Gemini CLI" --mood="reverent"

# 位置参数
/poem-writer "Gemini CLI" reverent

CLI 执行 prompts/get 方法，服务器将参数注入模板，返回最终 Prompt 文本，CLI 再发送给模型。

`/mcp` 交互命令

在 CLI 会话中：

bash

/mcp                   # 查看所有服务器状态和工具列表
/mcp list              # 列出服务器连接状态
/mcp reload            # 强制重新发现所有工具
/mcp auth <name>       # 触发 OAuth 认证流程
/mcp enable <name>     # 启用指定服务器（本次会话）
/mcp disable <name>    # 禁用指定服务器（本次会话）

`/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

Discovery State: COMPLETED

连接状态说明

状态	含义
`CONNECTED`	服务器已连接，工具可用
`CONNECTING`	连接进行中
`DISCONNECTED`	连接失败或出错
`Disabled`	已手动禁用

`gemini mcp` 管理命令

在终端（CLI 外）管理服务器配置，无需手动编辑 settings.json。

添加服务器

bash

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

常用选项：

选项	说明
`-s, --scope`	作用范围：`user`（`~/.gemini/`）或 `project`（`.gemini/`），默认 `project`
`-t, --transport`	传输类型：`stdio`、`sse`、`http`，默认 `stdio`
`-e, --env`	注入环境变量（可多次使用），格式 `-e KEY=value`
`-H, --header`	HTTP 请求头（SSE/HTTP 传输），格式 `-H "Authorization: Bearer xxx"`
`--timeout`	连接超时（毫秒）
`--trust`	跳过所有工具确认弹窗
`--include-tools`	工具白名单（逗号分隔）
`--exclude-tools`	工具黑名单（逗号分隔）

Stdio 服务器示例：

bash

# 本地服务器（自动推断 stdio 传输）
gemini mcp add -e API_KEY=123 -e DEBUG=true my-server /path/to/server arg1 arg2

# Python 服务器（注意 -- 分隔符防止 gemini 解析服务器参数）
gemini mcp add python-server python server.py -- --server-arg my-value

HTTP 服务器示例：

bash

gemini mcp add --transport http http-server https://api.example.com/mcp/

# 带认证头
gemini mcp add --transport http --header "Authorization: Bearer abc123" secure-server https://api.example.com/mcp/

SSE 服务器示例：

bash

gemini mcp add --transport sse sse-server https://api.example.com/sse/

列出服务器

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

注意：Stdio 服务器仅在当前目录被信任时才显示 Connected。使用 gemini trust 信任当前目录。

删除服务器

bash

gemini mcp remove <name>

# 删除用户配置中的服务器
gemini mcp remove -s user my-server

启用/禁用服务器

bash

# 持久禁用（写入 ~/.gemini/mcp-server-enablement.json）
gemini mcp disable my-server

# 仅本次会话禁用
gemini mcp disable my-server --session

# 重新启用
gemini mcp enable my-server

覆盖扩展提供的 MCP 配置

Extensions 提供的 MCP 服务器配置可以在本地 settings.json 中覆盖：

json

{
  "mcpServers": {
    "google-workspace": {
      "excludeTools": ["gmail.send"],
      "timeout": 30000
    }
  }
}

合并规则：

工具列表：按最严格策略合并（任意来源的排除生效，白名单取交集）
环境变量：合并 env 对象，本地值优先覆盖扩展默认值
标量字段（command、url、timeout 等）：本地值完全覆盖

故障排查

启动时静默诊断

为避免启动噪音，MCP 连接错误默认静默。如果有问题，只显示一行提示：

MCP issues detected. Run /mcp list for status.

详细诊断在以下情况自动开启：

运行 /mcp list、/mcp auth 等命令
模型尝试调用该服务器的工具
调用该服务器的 MCP Prompt

常见问题

服务器显示 DISCONNECTED

检查 command、args、cwd 字段是否正确
手动运行服务器命令，确认能独立启动
检查依赖是否安装（npm install、pip install）
查看 CLI 输出中的错误信息
确认 CLI 有执行该命令的权限

服务器已连接但无工具

确认服务器确实注册了工具（看代码或文档）
检查服务器是否正确实现了 MCP 工具列表协议
查看服务器 stderr 输出是否有报错
检查 includeTools/excludeTools 是否误过滤了所有工具

工具发现但执行失败

确认工具接受的参数格式
检查输入 Schema 是否合法 JSON Schema
确认服务器没有未处理的异常
考虑增大 timeout 值

沙箱兼容性问题

启用沙箱时 MCP 服务器可能受限：

使用 Docker 镜像（包含所有依赖）
确认可执行文件在沙箱内可访问
配置沙箱允许必要的网络连接

调试技巧：运行 CLI 时加 --debug 参数（或交互模式中按 F12）开启详细输出，MCP 服务器的 stderr 会被捕获记录（INFO 级别会过滤）。

安全注意事项

"trust": true 跳过所有确认弹窗，仅限完全受控的本地服务器使用
包含 API Key 或 Token 的环境变量应通过 environmentVariableRedaction 机制保护
使用宽泛权限的 GitHub PAT 可能导致跨仓库信息泄露
使用沙箱（沙箱安全隔离）可限制 MCP 服务器的系统访问范围

常见问题

Q: Stdio 服务器在 /mcp list 里显示 Disconnected，但命令本身能正常运行，怎么排查？

A: 最可能的原因是当前目录不受信任。Stdio 服务器出于安全原因，仅在受信任目录内才会自动连接。在终端运行 gemini trust 信任当前目录，然后重新打开 CLI。

Q: 同一服务器同时设置了 includeTools 和 excludeTools，以哪个为准？

A: excludeTools 始终优先。先从全量工具中排除 excludeTools 里的工具，再从剩余工具中只保留 includeTools 里的工具。如果某个工具同时在两个列表中，它会被排除。

Q: 如何查看某个 MCP 服务器提供了哪些工具？

A: 在 CLI 内运行 /mcp，会列出所有已连接服务器及其工具名列表。或从终端运行 gemini mcp list。

MCP 服务器完整参考 ​

架构概览 ​

传输方式 ​

Stdio（标准输入输出） ​

SSE（Server-Sent Events） ​

Streamable HTTP ​

完整配置字段参考 ​

环境变量展开 ​

环境变量脱敏 ​

OAuth 认证（远程服务器） ​

dynamic_discovery ​

google_credentials ​

service_account_impersonation ​

工具命名规范 ​

工具过滤 ​

工具执行流程 ​

确认机制 ​

工具结果处理 ​

富内容返回 ​

MCP Prompts 作为斜线命令 ​

服务器端定义示例 ​

调用方式 ​

/mcp 交互命令 ​

/mcp 输出示例 ​

连接状态说明 ​

gemini mcp 管理命令 ​

添加服务器 ​

列出服务器 ​

删除服务器 ​

启用/禁用服务器 ​

覆盖扩展提供的 MCP 配置 ​

故障排查 ​

启动时静默诊断 ​

常见问题 ​

安全注意事项 ​

常见问题 ​

MCP 服务器完整参考

架构概览

传输方式

Stdio（标准输入输出）

SSE（Server-Sent Events）

Streamable HTTP

完整配置字段参考

环境变量展开

环境变量脱敏

OAuth 认证（远程服务器）

dynamic_discovery

google_credentials

service_account_impersonation

工具命名规范

工具过滤

工具执行流程

确认机制

工具结果处理

富内容返回

MCP Prompts 作为斜线命令

服务器端定义示例

调用方式

`/mcp` 交互命令

`/mcp` 输出示例

连接状态说明

`gemini mcp` 管理命令

添加服务器

列出服务器

删除服务器

启用/禁用服务器

覆盖扩展提供的 MCP 配置

故障排查

启动时静默诊断

常见问题

安全注意事项

常见问题