MCP 入門

9.1 MCP 是什麼？

MCP 是 Model Context Protocol。對 Gemini CLI 來說，MCP server 是一個外接服務：它可以提供工具、資源與 prompts，讓模型在你的同意與設定範圍內查資料、呼叫 API、讀外部系統或執行特定流程。

9.2 mcpServers 設定範例

MCP 通常寫在 ~/.gemini/settings.json 或專案內的 .gemini/settings.json。先從專案設定開始，範圍比較清楚；secret 用環境變數，不要硬寫進 JSON。

{
  "mcpServers": {
    "project-docs": {
      "command": "node",
      "args": ["./mcp/project-docs/dist/server.js"],
      "cwd": ".",
      "env": {
        "DOCS_TOKEN": "$DOCS_TOKEN"
      },
      "timeout": 30000,
      "trust": false,
      "includeTools": ["search_docs", "read_doc"],
      "excludeTools": ["delete_doc", "write_doc"]
    }
  }
}

每個 server 一定要選一種連線方式，而且三選一、不能混用：本機執行檔用 command（走 stdio，行程之間用標準輸入輸出傳資料）；遠端 SSE 服務用 url；遠端 streamable HTTP 服務用 httpUrl。這三個欄位對應完全不同的連線邏輯，設定裡同時寫兩個也不會「兩個都試著連」，CLI 是照你填的欄位去判斷該用哪種協定。本機 server 會吃你的本機權限，所以先用最小工具集、短 timeout、trust: false。

欄位完整對照

上面的範例只用到 command、args、cwd、env、timeout、trust、includeTools、excludeTools 這幾個欄位，但每個 server 實際上還能設定更多可選欄位。平常用不到可以先跳過，但知道有這些選項存在，之後遇到企業內部 SSO、IAP 保護的服務這類進階場景，才不用整個重查一次文件。

env 環境變數：展開語法與自動遮蔽

env 區塊不是把值原封不動塞給 server，它支援簡單的展開語法：$VAR_NAME 與 ${VAR_NAME} 這兩種寫法跨平台都能用，Windows 專屬還多一種 %VAR_NAME%。CLI 啟動 server 前，會把這些寫法換成你目前終端機裡對應的環境變數值。

這裡有個容易漏掉的陷阱：如果你寫的變數名稱其實沒有被設定過，CLI 不會報錯，只會把它悄悄展開成空字串。你可能會看到 server「連線成功」，但工具一呼叫就卡在認證失敗，回頭才發現那個 token 從頭到尾都是空的——因為忘了在 shell 裡 export，或是名稱打錯字。改完 env 後，先確認變數名稱拼寫正確，再重新啟動 CLI 並用 /mcp list 或一個唯讀、無機密資料的工具呼叫驗證。不要用 echo 印出 token、key 或 password 的實際值；這些值可能被截圖、終端機紀錄或旁人看到。

幾種進階寫法，照抄改一改就能用

多數時候只需要最簡單的 stdio 設定，但下面幾種場景遲早會遇到，先看過範例，需要時直接改參數。

用 Docker 包裝的 server：不少官方 MCP server（例如 GitHub 官方提供的版本）建議直接跑現成的 Docker image，不用自己裝執行環境。

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server:latest"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
      }
    }
  }
}

設定前記得先在終端機把 token 匯出成環境變數（export GITHUB_PERSONAL_ACCESS_TOKEN="github_pat_..."），設完重開 CLI，跑一次 /mcp list，正常會看到類似「✓ github: docker ... - Connected」的狀態。

遠端 HTTP server 帶固定 token：不要把真實 token 直接寫進 settings.json、範例檔或會提交的專案檔。無論是 GitHub token 或遠端服務 token，都先在服務端建立僅限這次用途的最小權限憑證，再透過環境變數傳入該 MCP server。若服務只提供固定 token，也把它留在本機受保護的環境設定；設定檔只引用變數名稱，不放 token 本文。

{
  "mcpServers": {
    "httpServerWithAuth": {
      "httpUrl": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer ${MY_SERVICE_TOKEN}",
        "X-Custom-Header": "custom-value"
      },
      "timeout": 5000
    }
  }
          }

MY_SERVICE_TOKEN 是你本機已設定的環境變數名稱，不是可原樣複製的文字。這個 token 只交給你已審查、確定可信的 server；不用時就撤銷或移除。

IAP 保護的內部服務：要連的是被 Identity-Aware Proxy 擋住的 Cloud Run／GCP 服務時，不用手動跑一次 OAuth 瀏覽器授權，直接設定服務帳戶冒用即可。

{
  "mcpServers": {
    "myIapProtectedServer": {
      "url": "https://my-iap-service.run.app/sse",
      "authProviderType": "service_account_impersonation",
      "targetAudience": "YOUR_IAP_CLIENT_ID.apps.googleusercontent.com",
      "targetServiceAccount": "your-sa@your-project.iam.gserviceaccount.com"
    }
  }
}

targetAudience 放 IAP 的 OAuth client ID，targetServiceAccount 放要冒用的服務帳戶 email。這正是 Google 自家幾個 Cloud／Workspace 相關 MCP extension 在用的模式，企業內部要接類似架構的服務時，可以直接照抄改參數。

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

全域設定 vs 專案設定

MCP server 可以寫在兩個地方：家目錄底下的 ~/.gemini/settings.json（全域，這台電腦所有專案都看得到），或專案資料夾內的 .gemini/settings.json（只對這個專案生效）。兩邊都有 mcpServers 這個 key 時，專案層的設定優先權比較高。

這裡有一個容易想錯的地方：專案層設定生效的方式是「整個 mcpServers 這個 key 被取代」，不是逐欄位跟全域設定深層合併。如果全域設定裡有五個 server，專案設定裡只寫了一個，結果不會是「六個都在」，也不是「五個裡面被覆蓋一個」——而是專案這邊寫的那一個生效，其餘四個在這個專案底下等於沒設定過。跨專案有共用金鑰或工具集差異時，別假設專案沒寫到的欄位還會沿用全域預設值，需要的 server 就得在專案層重新完整寫一次。

如果你要接的服務已經有人包成現成的 extension（例如 GitHub、Google Cloud 一類常見工具），與其照抄一長串 mcpServers JSON，先查有沒有現成套件可以直接裝——這條路徑與它的完整介紹留到下一章 Extensions。

9.3 用 /mcp 檢查狀態

設定後重新啟動 Gemini CLI，先檢查 server 是否真的連上、有哪些工具暴露給模型。

/mcp
/mcp list
/mcp desc
/mcp schema
/mcp auth project-docs
/mcp enable project-docs
/mcp disable project-docs
/mcp reload

/mcp 或 /mcp list 是預設行為，列出目前設定的 server、連線狀態與各自暴露的工具；desc 額外附工具描述；schema 附完整 JSON schema，看每個工具吃什麼參數最準；auth 對需要 OAuth 的 server 啟動授權流程；enable／disable 可以暫時關掉某個 server 而不用動設定檔——9.6 排查「一台拖累全部」的情境會直接用到這一組；reload 重新探索所有 server 目前有哪些工具，改了 server 端的工具定義後很常用到。這是目前官方文件列出的子指令；Gemini CLI 版本迭代快，加上產品正處於向 Antigravity CLI 過渡期，實際跑出來的清單若有出入，以當下 gemini --help、/mcp 現場輸出與官方文件為準。

殼層底下的 gemini mcp 指令

前面那組 /mcp 指令，都是進到 Gemini CLI 互動模式之後才打得到的。還有另一組指令活在互動模式之外——直接在終端機的殼層底下打 gemini mcp，用來管理設定檔，不需要先啟動 CLI 再操作。

gemini mcp add --scope project --transport stdio \
  --env API_KEY=$API_KEY --trust myServer "node" "./server.js"
gemini mcp list
gemini mcp remove myServer -s user

add 常用的選項：-s／--scope 指定寫進 user（全域）還是 project（專案），預設 project；-t／--transport 指定 stdio／sse／http，預設 stdio；-e／--env、-H／--header 對應設定檔裡的 env、headers；還有 --timeout、--trust、--description、--include-tools、--exclude-tools。這組指令的價值在於可以寫進團隊的 onboarding script，讓新成員不用手動編輯 JSON、跑一行指令就把該裝的 MCP server 裝好，比貼一整段設定檔給對方複製貼上可靠。

9.4 include/exclude 的安全用法

includeTools 是 allowlist：只開你列出的工具。excludeTools 是 veto：即使工具同時在 include 裡，也會被排除。新 server 先用 include，確認每個工具的輸入、輸出與副作用後再放寬。

{
  "mcpServers": {
    "filteredServer": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "includeTools": ["safe_tool", "file_reader"],
      "excludeTools": ["dangerous_tool"]
    }
  }
}

這個例子裡，即使 my_mcp_server 本身還提供其他工具，模型也只看得到 safe_tool 跟 file_reader；如果哪天 dangerous_tool 不小心也被加進 includeTools，excludeTools 仍然會把它擋下來——兩份清單同時列到同一個工具名稱，永遠是 exclude 贏。

• 不要把 excludeTools 當成唯一安全機制；它降低誤用機率，不是 sandbox，工具本身該有的權限邊界還是要 server 端自己把關。
• 給 token 時用最小 scope，並只在該 server 自己的 env 裡明確傳給需要的 server——上一節提過，沒明寫的敏感變數會被自動遮蔽擋掉，這其實也是一種天然的最小授權提醒。

工具命名衝突與消歧

多個 server 剛好提供同名工具時，Gemini CLI 會自動加前綴消歧，型式大致是 serverName__toolName 這樣；名稱裡的非英數字元會被換成底線，太長的名稱會截斷、中間補上 ...。官方文件也提醒，取 MCP server 名稱時最好避開底線，免得跟 CLI 自動加的前綴混在一起，分不清哪段是 server 名、哪段是工具名。

比較麻煩的是，就算有消歧前綴，模型仍可能因為兩個同名工具的描述不夠清楚而選錯 server，而且過程不會有明顯報錯。發現「Gemini 好像呼叫錯 server 的工具」時，先去 /mcp schema 對照兩邊工具的實際描述與參數，通常比懷疑模型「理解錯」更快找到答案。

團隊層級的白名單／黑名單

如果你在管一個團隊或企業環境，需要的是「不管使用者自己在本機加了什麼 server，都只有核准過的能生效」——個別 server 的 trust 欄位管不到這件事，那是每個 server 自己的授權開關，不是全域門禁。真正的門禁在 settings.json 最外層的 mcp 物件：mcp.allowed 是白名單陣列，設定後只有列在裡面的 server 會被連線；mcp.excluded 是黑名單；mcp.serverCommand 可以設定全域統一的啟動指令。這一層跟每個 server 自己的 trust 是分開的機制，能防止有人自己在本機加一個「自認安全」的新 server 就直接生效。

9.5 Resources 與 prompts

有些 MCP server 會提供 resources。Gemini CLI 會在探索時列出它們，你可以像引用檔案一樣用 @server://resource/path 把內容放進對話。這適合只讀文件、報表、API payload 或查詢結果。

@project-docs://guides/release-checklist
請根據這份 release checklist，幫我檢查目前 PR 還缺哪些步驟。

MCP prompts 則會變成可呼叫的 slash command。它適合包裝固定流程，例如 release review、客服摘要或資料品質檢查。prompt 由 server 回傳內容，CLI 再送給模型執行。

/release-review --version="2.4.0" --base="main"

如果你自己動手寫 MCP server，還有一個對使用體驗很有幫助、卻不是每個人都知道的細節：工具的回傳結果不是只能塞純文字。官方的 CallToolResult 格式允許同一次回應裡混合文字、圖片（Base64 加 mimeType）、音檔、resource 或 resource link，Gemini CLI 收到後會自動拆開處理——文字合併進模型看到的內容，二進位資料包成對應格式——不需要在使用端額外設定，也不需要 server 端自己把圖片硬轉成文字塞進去。工具想回傳一張截圖或一段錄音，直接回傳對應的 content 類型即可。

9.6 疑難排解

多數 MCP 疑難雜症都跟連線設定或執行環境有關，很少是模型本身的問題。養成先看 /mcp list、確認基本設定正確，再往下深挖的習慣，能省下大半排查時間。下面先列常見狀況的速查表，兩個比較棘手、需要多幾個步驟才能定位的情境，表格後面另外展開說明。

一台掛掉、拖累全部連鎖失敗

設定裡同時掛好幾個 server 時，有一種狀況特別容易誤判：只要其中一台在啟動握手階段失敗，可能會拖累甚至中斷其他原本正常的 server 探索流程，畫面上看到的是一長串像整體崩潰的錯誤，例如 MCP error -32000: Connection closed 或 TypeError: fetch failed。第一直覺常常是「是不是整包設定都壞了」，但多數時候只是其中一台拖累全局。

排除法是二分法，不是重裝全部：用 /mcp disable 一次關掉一半可疑的 server，重開確認錯誤消失沒有，再逐步縮小範圍，找到真正出問題的那一台，其餘的維持原設定即可。這也是 9.3 提過 /mcp enable／disable 的實際用途——不用刪設定檔就能暫時隔離一台 server。

明明終端機打得動，MCP 子行程卻說找不到指令

另一種常見的困惑是：你在終端機直接打某個指令完全正常，寫進 command 欄位讓 MCP 子行程去跑，卻回報找不到執行檔。常見原因是 CLI 產生 MCP 子行程時，不是完整繼承你目前互動終端機的那份環境，而是用相對精簡過的一份——透過 nvm、Homebrew、asdf 這類版本管理工具安裝、只在你互動 shell 的 PATH 裡才找得到的執行檔，換到子行程的精簡環境裡就找不到了。

修法很直接：command 欄位不要只寫指令名稱，改成絕對路徑（跑一次 which node 或 which npx 查出實際路徑貼上去），或是在該 server 自己的 env 裡明確帶入完整的 PATH。

另一個相關但成因不同的狀況：command 設成 npx，如果是第一次執行、套件還沒下載過，npx 會卡在下載安裝的過程，而這個過程可能超出 CLI 探索工具列表（tools/list）的逾時窗口，表現得像連線整個 hang 住。如果確認這個 MCP server 的官方文件支援全域安裝，而且你本來就使用 Node/npm，再考慮依官方指示安裝後把 command 指向該執行檔。不要只為了排除逾時就猜著執行 npm install -g，也不要混用 npx、全域 npm 與其他安裝方式。不確定時，先保留 npx、提高該 server 的啟動逾時，並依 server 官方文件排查。

排查的順序建議先用 /mcp list 或 shell 裡的 gemini mcp list 看整體狀態，訊息不夠再用 --debug 重開、或直接在終端機跑一次 server 本身取得最原始的錯誤輸出；9.3 提過的 MCP Inspector 也很適合在這一步拿來單獨排除「是 server 的問題還是 CLI 設定的問題」。

本章小結

MCP 是 Gemini CLI 擴充能力的入口，運作分成三層：先在 settings.json 選對連線方式（stdio／SSE／streamable HTTP 三選一）、把 timeout、trust、includeTools／excludeTools 這些安全欄位設好；再用 /mcp（互動模式內）或 gemini mcp（殼層底下）確認連線與工具清單；最後才是善用 resources 與 prompts，把常見查詢與固定流程變成可重複的工作習慣。安全上的底線很單純：新 server 先窄後寬，trust: true 只留給自己完全控制的 server，token 一律走環境變數、只在需要的 server 明確傳入。連線出狀況時，記得 MCP 的異常預設是安靜的——沒跳錯誤不代表沒事，先用 /mcp list 或 MCP Inspector 動手確認，比憑感覺猜快得多。

動手試試

1. 打開目前專案的 .gemini/settings.json，草擬一個只讀 MCP server 設定，不放真 token。
2. 啟動 Gemini CLI 後跑 /mcp list、/mcp desc，確認工具名稱和描述是否清楚。
3. 把範例中的 includeTools 改成只允許一個讀取工具，觀察 /mcp schema 的變化。
4. 若 server 有 resources，試著用 @server://... 引用一筆只讀資料並要求 Gemini 摘要。
5. 故意把一個 streamable HTTP server 的 httpUrl 打錯寫成 url，重開 CLI 觀察實際跳出的錯誤訊息，親眼看一次「選錯 transport key」的症狀長怎樣。
6. 跑一次 npx @modelcontextprotocol/inspector 搭配手邊的 server，在完全不開 Gemini CLI 的情況下，確認 server 本身能不能正常回應工具列表。