---
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="/zh-Hant/docs/gemini-cli/official/03-tools-mcp/37-mcp-resources" />
  <Card title="MCP 設定" description="回看 settings.json、環境變數和憑據傳遞的最小許可權做法。" href="/zh-Hant/docs/gemini-cli/official/03-tools-mcp/35-mcp-setup" />
  <Card title="Policy engine" description="寫操作工具需要繼續用 policy 控制引數和路徑。" href="/zh-Hant/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)
