---
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="/zh-Hant/docs/gemini-cli/official/03-tools-mcp/36-mcp-server" />
  <Card title="Settings" description="MCP server 通常要寫進 settings.json，並做好使用者級/專案級分層。" href="/zh-Hant/docs/gemini-cli/official/02-context-config/20-settings" />
  <Card title="Policy engine" description="有寫許可權的 MCP，要繼續用 policy 控制工具引數。" href="/zh-Hant/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)
