Codex CLI 連結多個 Gmail 帳戶：MCP 多帳戶完整設定指南

AI
, , , ,
1

學習在 Codex CLI 使用 gmail-mcp-multi、gmail-mcp-multiauth 或 Composio 串接多組 Gmail，含 OAuth 設定、config.toml 範例與架構選型建議。

核心架構：MCP 伺服器做為 Codex CLI 與 Gmail API 的橋樑

Model Context Protocol (MCP) 伺服器負責將 Codex CLI 的自然語言指令轉換為 Gmail API 呼叫。關鍵在於每個 Gmail 帳戶需獨立完成 OAuth 2.0 授權並保存各自的 token，MCP 伺服器再透過「帳戶別名」或「獨立伺服器實例」區分不同信箱。

在 ~/.codex/config.toml 註冊一或多個 MCP 伺服器後，Codex 執行時即可呼叫搜尋信件、寄信等工具。

方案一：gmail-mcp-multi —— 單一伺服器管理多帳戶

適合：帳戶數量多、需在同一 session 內快速切換。

設定步驟

  1. 安裝套件

    npm install -g gmail-mcp-multi
# 或直接使用 npx gmail-mcp-multi

  2. 建立 Google Cloud OAuth 憑證

    • 在 Google Cloud Console 建立專案並啟用 Gmail API
    • 建立「Desktop app」類型的 OAuth 2.0 用戶端 ID
    • 下載 JSON 並存為 ~/.gmail-mcp/oauth-keys.json

  3. 註冊 MCP 伺服器
    在 ~/.codex/config.toml 加入：

    [mcp_servers.gmail-multi]
command = "npx"
args = ["gmail-mcp-multi"]

  4. 逐帳戶授權
    伺服器啟動後，使用內建 authenticate 工具：

    authenticate({ alias: "work", email: "[email protected]" })

authenticate({ alias: “personal”, email: “[email protected]” })


5. **呼叫時指定帳戶**
所有 Gmail 工具需帶 `account` 參數：
```json
search_emails({ account: "work", query: "in:inbox is:unread" })

方案二：gmail-mcp-multiauth —— 每帳戶獨立進程完全隔離

適合：帳戶間需嚴格隔離、避免 token 互相污染、未來可能接入團隊共用。

設定步驟

  1. 準備共用 OAuth 憑證
    同一組 Google Cloud OAuth 應用可服務多個帳戶，存為 gcp-oauth.keys.json。

  2. 建立獨立資料夾與環境變數

    mkdir -p ~/.gmail-personal ~/.gmail-business
cp gcp-oauth.keys.json ~/.gmail-personal/
cp gcp-oauth.keys.json ~/.gmail-business/

  3. 分別授權

    # 個人帳戶
GMAIL_OAUTH_PATH=~/.gmail-personal/token.json \
GMAIL_CREDENTIALS_PATH=~/.gmail-personal/gcp-oauth.keys.json \
npx -y @jessicaoy89/gmail-mcp auth

# 商務帳戶
GMAIL_OAUTH_PATH=~/.gmail-business/token.json \
GMAIL_CREDENTIALS_PATH=~/.gmail-business/gcp-oauth.keys.json \
npx -y @jessicaoy89/gmail-mcp auth

    每次會開啟瀏覽器登入對應的 Google 帳戶。

  4. 撰寫啟動腳本 (start-mcp.sh)

    #!/bin/bash
export GMAIL_OAUTH_PATH=~/.gmail-personal/token.json
export GMAIL_CREDENTIALS_PATH=~/.gmail-personal/gcp-oauth.keys.json
exec npx -y @jessicaoy89/gmail-mcp

    為每個帳戶建立對應腳本並賦予執行權限。

  5. 註冊多個獨立 MCP 伺服器

    [mcp_servers.gmail-personal]
command = "~/.gmail-personal/start-mcp.sh"

[mcp_servers.gmail-business]
command = "~/.gmail-business/start-mcp.sh"

操作時直接呼叫對應伺服器的工具，無需額外帶 account 參數。

方案三：Composio 代管平台 —— 免自架 OAuth 的雲端整合

適合：不想處理 Google Cloud 設定、偏好雲端統一管理。

  1. 執行 Composio 安裝指令，系統自動開啟瀏覽器完成授權。
  2. 重複授權流程分別連結不同 Google 帳戶到同一 Composio 帳號。
  3. 在工作流程中指定使用哪個已連結帳戶。

Codex CLI、VS Code、Codex App 均可透過自然語言操作。

跨平台替代方案：Nylas MCP

若需同時管理 Gmail、Outlook 等多種信箱服務，可考慮 Nylas MCP。在 config.toml 以 Bearer token 驗證接入，犧牲部分 Gmail 專屬功能，換取跨平台一致操作體驗。

選型建議

需求場景 建議方案
2-3 個帳戶、設定最簡單 gmail-mcp-multi
帳戶嚴格隔離、團隊共用規劃 gmail-mcp-multiauth
完全不想碰 Google Cloud 設定 Composio
需整合 Outlook 等非 Gmail 服務 Nylas MCP

常見坑點提醒

  • OAuth 同意畫面：開發階段需將應用類型設為「外部」並加入測試用戶，否則授權會被封鎖。
  • Token 刷新：長期運行需確保 refresh token 有效，建議定期驗證或實作自動刷新機制。
  • 權限範圍：最小權限原則，僅申請 gmail.readonly、gmail.send 等必要 scope。
  • 環境變數衝突：多進程方案務必確認各進程的 GMAIL_OAUTH_PATH、GMAIL_CREDENTIALS_PATH 互不干擾。