---
title: "MCP 设置"
description: "Gemini CLI MCP 设置方式：settings.json、环境变量、stdio/HTTP/SSE server、认证和最小权限原则。"
verifiedAt: "2026-05-09"
---

MCP 让 Gemini CLI 可以连接外部工具和服务。官方 MCP tutorial 展示了通过 `settings.json` 配置 MCP server，也有 CLI cheatsheet 中的 `gemini mcp add` 管理命令。

> [!IMPORTANT]
> **先接只读 MCP**：第一次接外部系统，优先只读权限。确认稳定后再开放写操作。

## CLI 管理命令示例

常见动作包括添加 stdio server、添加 HTTP server、列出 server、移除 server。对应命令是 `gemini mcp add ...`、`gemini mcp list`、`gemini mcp remove ...`。

## settings.json 配置思路

MCP server 常见字段包括 command、args、env。凭据通过环境变量传入，不要硬编码在配置里。

最小配置思路是：`mcpServers.github.command` 指向启动命令，`args` 放 server 参数，`env` 只引用外部环境变量，例如 `${GITHUB_PERSONAL_ACCESS_TOKEN}`。不要把 token 明文写进 `settings.json`。

官方 GitHub MCP 示例使用 Docker 启动 server，并把本机环境变量映射进容器。关键点不是 Docker，而是“配置里只写变量名，不写 token 值”。团队教程里应展示占位变量，不展示真实 PAT。

## 最小设置流程

1. 先确认 MCP server 能在终端单独启动。
2. 准备最小权限凭据，例如 GitHub fine-grained PAT。
3. 把凭据放进本机环境变量或凭据管理，不写进仓库。
4. 在用户级或项目级 `settings.json` 增加 `mcpServers`。
5. 重启 Gemini CLI 或执行 `/mcp reload`。
6. 运行 `/mcp list`，确认 server 是 connected。
7. 先调用只读工具，再逐步验证写工具。

## 权限建议

- GitHub PAT 用 fine-grained token。
- 只给需要的 repo 和 scope。
- 能只读就不写。
- 不把 token 写入仓库。
- 用 `/mcp list` 验证加载结果。

| 配置项 | 建议 | 风险 |
| --- | --- | --- |
| `command` / `args` | 指向明确 server 启动命令 | 启动脚本过宽可能执行额外逻辑 |
| `env` | 只引用环境变量名 | 明文 token 泄露到仓库 |
| 用户级配置 | 放个人工具 | 团队不可复现 |
| 项目级配置 | 放团队共享 server | 需要脱敏和最小权限 |
| 写权限工具 | 单独验证确认弹窗 | 误写 issue、PR、数据库或云资源 |

## 常见失败

- Docker 没启动或镜像拉取失败。
- 环境变量在当前 shell 不存在。
- PAT scope 不够，读 repo 可以但写 issue / PR 失败。
- server 启动成功但工具没有被发现，需要 `/mcp reload`。
- 项目级配置和用户级配置同名冲突。

## 只读到写入的演练

接 GitHub、数据库、云服务这类 MCP 时，不要第一次就测试写操作。更稳的演练顺序是：

1. 列出当前 server 暴露的工具。
2. 执行一个只读查询，例如列 repo、读 issue、查 schema。
3. 确认返回内容不包含不该暴露的密钥或隐私数据。
4. 再测试一个低风险写操作，例如在测试 repo 创建草稿 issue。
5. 确认写操作仍然有确认提示或 policy 限制。

如果只读查询都不稳定，先修 server、凭据和网络，不要急着开放写权限。

## 验收方式

不要只看 `/mcp list` connected。还要让 Gemini CLI 列出该 server 暴露的 tools/resources，并执行一个低风险只读动作。涉及写操作的 MCP，要确认 CLI 仍然弹出工具确认或受 policy 控制。

## 接下来去哪

<Cards>
  <Card title="MCP server" description="继续看 server 工具、resources、prompts 如何暴露给 Gemini CLI。" href="/docs/gemini-cli/official/03-tools-mcp/36-mcp-server" />
  <Card title="Settings" description="MCP server 通常要写进 settings.json，并做好用户级/项目级分层。" href="/docs/gemini-cli/official/02-context-config/20-settings" />
  <Card title="Policy engine" description="有写权限的 MCP，要继续用 policy 控制工具参数。" href="/docs/gemini-cli/official/06-security-enterprise/61-policy-engine" />
</Cards>

## 官方来源

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