搭配 Gemini CLI 使用 MCP 伺服器

{ ...file contains other config objects
  "mcpServers": {
    "serverName": {
      "command": "path/to/server",
      "args": ["--arg1", "value1"],
      "env": {
        "API_KEY": "$MY_API_TOKEN"
      },
      "cwd": "./server-directory",
      "timeout": 30000,
      "trust": false
    }
  }
}

設定屬性

每個伺服器設定支援以下屬性：

必要項（以下擇一）

command (字串): Stdio 傳輸的可執行檔路徑
url (字串): SSE 端點 URL（例如："http://localhost:8080/sse"）
httpUrl (字串): HTTP 串流端點 URL

選項

args (字串[]): Stdio 傳輸的命令列參數
env (物件): 伺服器程序的環境變數。值可以使用 $VAR_NAME 或 ${VAR_NAME} 語法來引用環境變數
cwd (字串): Stdio 傳輸的工作目錄
timeout (數字): 請求逾時時間，單位為毫秒（預設值：600,000 毫秒 = 10 分鐘）
trust (布林值): 若為 true，則會略過此伺服器的所有工具呼叫確認（預設值：false）

設定範例

Python MCP 伺服器 (Stdio)

{
  "mcpServers": {
    "pythonTools": {
      "command": "python",
      "args": ["-m", "my_mcp_server", "--port", "8080"],
      "cwd": "./mcp-servers/python",
      "env": {
        "DATABASE_URL": "$DB_CONNECTION_STRING",
        "API_KEY": "${EXTERNAL_API_KEY}"
      },
      "timeout": 15000
    }
  }
}

Node.js MCP 伺服器 (Stdio)

{
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["dist/server.js", "--verbose"],
      "cwd": "./mcp-servers/node",
      "trust": true
    }
  }
}

基於 Docker 的 MCP 伺服器

{
  "mcpServers": {
    "dockerizedServer": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "API_KEY",
        "-v",
        "${PWD}:/workspace",
        "my-mcp-server:latest"
      ],
      "env": {
        "API_KEY": "$EXTERNAL_SERVICE_TOKEN"
      }
    }
  }
}

基於 HTTP 的 MCP 伺服器

{
  "mcpServers": {
    "httpServer": {
      "httpUrl": "http://localhost:3000/mcp",
      "timeout": 5000
    }
  }
}

探索流程深度解析

當 Gemini CLI 啟動時，它會透過以下詳細流程執行 MCP 伺服器探索：

1. 伺服器迭代與連線

對於 mcpServers 中每個已設定的伺服器：

開始追蹤狀態： 伺服器狀態設為 CONNECTING
選擇傳輸機制： 根據設定屬性：
- httpUrl → StreamableHTTPClientTransport
- url → SSEClientTransport
- command → StdioClientTransport
建立連線： MCP 客戶端會嘗試在設定的逾時時間內連線
錯誤處理： 連線失敗會被記錄下來，且伺服器狀態會設為 DISCONNECTED

2. 工具探索

成功連線後：

工具清單： 客戶端會呼叫 MCP 伺服器的工具清單端點
結構驗證： 每個工具的函式宣告都會經過驗證
名稱清理： 清理工具名稱以符合 Gemini API 的要求：
- 無效字元（非英數字元、底線、點、連字號）將被底線取代
- 長度超過 63 個字元的名稱將會被截斷，並在中間以 ___ 取代

3. 衝突解決

當多個伺服器公開同名工具時：

先註冊者優先： 第一個註冊工具名稱的伺服器會獲得無前綴的名稱
自動加上前綴： 後續的伺服器會獲得加上前綴的名稱：serverName__toolName
註冊表追蹤： 工具註冊表會維護伺服器名稱與其工具之間的對應關係

4. 結構處理

工具參數結構會經過清理，以確保與 Gemini API 的相容性：

$schema 屬性會被移除
additionalProperties 會被去除
帶有 default 的 anyOf 其預設值會被移除（為與 Vertex AI 相容）
遞迴處理適用於巢狀結構

5. 連線管理

探索完成後：

持續連線： 成功註冊工具的伺服器會維持其連線
清理： 未提供任何可用工具的伺服器，其連線將被關閉
狀態更新： 最終的伺服器狀態會設為 CONNECTED 或 DISCONNECTED

工具執行流程

當 Gemini 模型決定使用 MCP 工具時，會發生以下執行流程：

1. 工具呼叫

模型會產生一個 FunctionCall，其中包含：

工具名稱： 已註冊的名稱（可能帶有前綴）
引數： 符合工具參數結構的 JSON 物件

2. 確認流程

每個 DiscoveredMCPTool 都實作了精密的確認邏輯：

基於信任的繞過機制

if (this.trust) {
  return false; // 不需要確認
}

動態允許清單

系統會為以下項目維護內部允許清單：

伺服器層級： serverName → 此伺服器的所有工具皆受信賴
工具層級： serverName.toolName → 此特定工具受信賴

使用者選擇處理

需要確認時，使用者可以選擇：

執行一次： 僅執行這一次
一律允許此工具： 新增至工具層級的允許清單
一律允許此伺服器： 新增至伺服器層級的允許清單
取消： 中止執行

3. 執行

確認後（或信任繞過後）：

參數準備： 根據工具的結構驗證引數

MCP 呼叫： 底層的 CallableTool 會透過以下方式呼叫伺服器：

const functionCalls = [
  {
    name: this.serverToolName, // 原始伺服器工具名稱
    args: params,
  },
];

回應處理： 結果會被格式化，以便用於 LLM 情境和使用者顯示

4. 回應處理

執行結果包含：

llmContent: 用於語言模型情境的原始回應部分
returnDisplay: 用於使用者顯示的格式化輸出（通常是 markdown 程式碼區塊中的 JSON）

如何與您的 MCP 伺服器互動

使用 `/mcp` 指令

/mcp 指令提供關於您 MCP 伺服器設定的全面資訊：

/mcp

這會顯示：

伺服器清單： 所有已設定的 MCP 伺服器
連線狀態： CONNECTED、CONNECTING 或 DISCONNECTED
伺服器詳細資料： 設定摘要（不含敏感資料）
可用工具： 來自每個伺服器的工具清單及其說明
探索狀態： 整體探索流程的狀態

`/mcp` 輸出範例

MCP 伺服器狀態：

📡 pythonTools (CONNECTED)
  指令：python -m my_mcp_server --port 8080
  工作目錄：./mcp-servers/python
  逾時：15000ms
  工具：calculate_sum, file_analyzer, data_processor

🔌 nodeServer (DISCONNECTED)
  指令：node dist/server.js --verbose
  錯誤：連線被拒

🐳 dockerizedServer (CONNECTED)
  指令：docker run -i --rm -e API_KEY my-mcp-server:latest
  工具：docker__deploy, docker__status

探索狀態：COMPLETED