---
title: "MCP server"
description: "Gemini CLI MCP server 管理：stdio、HTTP、SSE、header、环境变量、启停、reload、OAuth auth 和工具列表。"
verifiedAt: "2026-05-09"
---

Gemini CLI 支持配置和管理 MCP server。官方 command reference 中 `/mcp` 可 list、reload、enable、disable、auth、schema；CLI cheatsheet 里也有 `gemini mcp add/remove/list`。

MCP server 是 Gemini CLI 和外部系统之间的桥。它可以暴露 tools，也可以暴露 resources。Tools 是动作，resources 是可读上下文；设计 MCP 时应先开放 resources，再开放写工具。

> [!IMPORTANT]
> MCP server 的关键不是“能连上”，而是它暴露了哪些工具、拿到了哪些凭据、写操作是否仍受确认和 policy 控制。

## 常见 transport

| 类型 | 适合 |
| --- | --- |
| stdio | 本地命令或 Docker server |
| HTTP | 本地或远程 HTTP MCP endpoint |
| SSE | Server-sent events endpoint |

| 场景 | 推荐 transport | 说明 |
| --- | --- | --- |
| 本地 CLI / Docker server | stdio | 易于本机调试和隔离 |
| 内网服务 | HTTP | 适合已有服务化 endpoint |
| 远端事件流 | SSE | 适合需要持续事件连接的 server |
| 需要浏览器 OAuth | HTTP / SSE | headless 环境要提前处理回调问题 |

## 示例

HTTP server 可以用 `gemini mcp add api-server http://localhost:3000 --transport http`。SSE endpoint 可以用 `--transport sse`。需要 header 时用 `--header` 传入，但不要把真实 token 写进共享文档或仓库。

在 `settings.json` 里，stdio server 通常使用 `command`、`args`、`env`、`cwd`；远端 server 使用 `url` 或 `httpUrl`，可加 `headers`、`timeout`、`includeTools`、`excludeTools`、`trust`。`trust: true` 会绕过该 server 的工具确认，除非是企业内部强信任 server，否则不要默认开启。

## `trust: true` 边界

`trust: true` 只适合你完全控制、工具参数可审计、失败后果可接受的 server。公开教程和团队默认配置里，不建议把它当成省确认步骤的快捷方式。尤其是 GitHub、数据库、云资源、文件系统、发布系统这类 server，写操作应该保留确认或 policy 限制。

更稳的做法是先用 `includeTools` 只开放必要工具，再用 `excludeTools` 禁掉高风险动作，最后用 policy 约束参数。

## 环境变量和脱敏

Gemini CLI 会对继承自宿主环境的敏感变量做自动 redaction，例如包含 `TOKEN`、`SECRET`、`PASSWORD`、`KEY`、`AUTH`、`CREDENTIAL` 的变量。要把某个变量传给指定 MCP server，必须在该 server 的 `env` 中显式声明。

这不是麻烦，而是知情同意：你明确告诉 CLI“这个 server 可以拿到这个变量”。即便如此，也应使用 `$VAR` 或 `${VAR}` 引用，不要硬编码明文。

## OAuth remote MCP

远端 SSE / HTTP MCP server 支持 OAuth 2.0。server 返回 401 后，CLI 可发现 OAuth endpoints、打开浏览器认证、保存 token 并重试连接。这个流程要求本机能打开浏览器并接收 localhost callback；headless 环境通常不适合这种交互式 OAuth。

## 交互式命令

交互式会话里常用 `/mcp list`、`/mcp reload`、`/mcp disable <server>`、`/mcp enable <server>`、`/mcp auth <server>`、`/mcp schema`。

## 排错顺序

1. server 是否能单独启动。
2. 环境变量是否存在。
3. token scope 是否足够。
4. transport 是否配置正确。
5. `/mcp reload` 后是否能列出工具。
6. `includeTools` / `excludeTools` 是否把目标工具过滤掉。
7. 远端 OAuth 是否能完成浏览器回调。

## 验收方式

验收一个 MCP server，要覆盖连接、工具发现、resource 读取、只读工具调用、写工具确认五项。只验证“能连上”不够；很多风险出在工具权限和凭据传递。

## 接下来去哪

<Cards>
  <Card title="MCP resources" description="先暴露只读 resources，再考虑有副作用的 tools。" href="/docs/gemini-cli/official/03-tools-mcp/37-mcp-resources" />
  <Card title="MCP 设置" description="回看 settings.json、环境变量和凭据传递的最小权限做法。" href="/docs/gemini-cli/official/03-tools-mcp/35-mcp-setup" />
  <Card title="Policy engine" description="写操作工具需要继续用 policy 控制参数和路径。" href="/docs/gemini-cli/official/06-security-enterprise/61-policy-engine" />
</Cards>

## 官方来源

- [Gemini CLI MCP server reference](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md)
- [Gemini CLI MCP resources](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-resources.md)
