建立 2026-09-19 更新 2026-09-19

MCP 外部工具

模型情境協定（Model Context Protocol, MCP）是連接代理與外部工具的開放標準。接上 MCP 伺服器後，代理就能查資料庫、讀 API 文件、操作開發工具，而不只是看你的專案檔案。

設定檔位置

範圍	位置
全域	`~/.gemini/config/mcp_config.json`
工作區	`.agents/mcp_config.json`

也可以在介面中管理：CLI 輸入 /mcp；2.0 桌面 App 在「Settings → Customizations → Installed MCP Servers」；IDE 在代理側邊面板的 MCP Servers。

格式

設定檔只有一個 mcpServers 物件，每個伺服器一個項目。

本機伺服器（stdio）

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"],
      "env": {
        "EXAMPLE_VAR": "value"
      }
    }
  }
}

遠端伺服器（HTTP／SSE）

{
  "mcpServers": {
    "my-remote-server": {
      "serverUrl": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

欄位名稱是 serverUrl

遠端伺服器的網址欄位是 serverUrl。Gemini CLI 的 url、httpUrl 在這裡不適用，遷移時要改。

欄位速查

欄位	說明
`command`＋`args`	本機伺服器的執行檔與參數（stdio 傳輸；與 `serverUrl` 二選一）
`serverUrl`	遠端 HTTP／SSE 伺服器網址
`env`	環境變數
`cwd`	工作目錄
`headers`	自訂 HTTP 標頭，常用來放 API token
`authProviderType`	設為 `"google_credentials"` 可使用 Google 應用程式預設憑證（ADC）
`oauth`	OAuth 憑證（`clientId`、`clientSecret`）；也支援動態註冊
`disabled`	設為 `true` 暫時停用，不必刪除設定
`disabledTools`	列出要禁止代理使用的工具名稱

安全提醒

MCP 伺服器能執行程式碼或存取你的資料，只安裝可信任來源的伺服器。
Token 不要直接寫進會進版控的 .agents/mcp_config.json；改放在個人的全域設定，或用環境變數。
用 disabledTools 拿掉你不需要、風險較高的工具（例如寫入或刪除類）。

完成設定後，用 /mcp 確認伺服器已連線，再請代理實際呼叫一次驗證。