Pidgeon

npx add-mcp 'https://pidgeon.ai/api/mcp'

Agent 可以直接管理 Pidgeon 收件匣：讀取、回覆，並在其中建立地址。Pidgeon 透過與本文檔所述相同的 API 使用 Model Context Protocol——這只是協定轉接器，僅此而已。

有兩種接入方式，但它們使用的是同一個伺服器。託管版本無需安裝；套件則會在你的電腦上執行伺服器。

託管版本，也就是一個 URL

claude mcp add --transport http pidgeon https://pidgeon.ai/api/mcp

第一次呼叫會回覆 401，並將用戶端導向 Pidgeon 登入。你可以選擇它能做什麼——讀取、讀取並傳送，或完整存取——以及它能存取哪些內容：一個地址，或在你擁有該帳戶時存取所有地址。這項選擇會成為 API 金鑰，而用戶端會持有該金鑰的權杖。它會顯示在 Developers → API keys → Connected apps 下方；在那裡按下 Disconnect，會在用戶端下次呼叫時中止連線。

Claude 的自訂連接器、ChatGPT、Grok、Cursor、Codex 和 VS Code 都使用相同的 URL，並以相同方式登入。每個請求都會獨立處理：伺服器不會保留工作階段，因為它沒有需要保存的自身狀態。

若要讓無人在場登入的 agent 使用，請改為提供金鑰：

claude mcp add --transport http pidgeon https://pidgeon.ai/api/mcp \
--header "Authorization: Bearer $PIDGEON_API_KEY"

x-api-key 也可以使用。Cursor、Codex（讀取 TOML，而非 JSON）和 VS Code 的逐步說明；Windsurf 和 Gemini CLI 使用相同的 URL 和標頭。

在 Grok 中

在 Grok 中，前往 Connectors → Custom，貼上 https://pidgeon.ai/api/mcp，並在同意畫面登入；不需要金鑰（逐步說明）。Meta 的 Muse 正在 Meta 審核中。

在 Cursor 中

從 cursor.directory 列表中**將 Pidgeon 加入 Cursor**，其中包含託管伺服器和 skill。

或者手動新增伺服器，放在 ~/.cursor/mcp.json（或單一專案使用的 .cursor/mcp.json）中。它只需要 URL；Cursor 會在第一次呼叫時讓你登入：

{
"mcpServers": {
  "pidgeon": {
    "url": "https://pidgeon.ai/api/mcp"
  }
}
}

若要讓無人在場登入的 agent 使用，請在 URL 旁新增 "headers": { "Authorization": "Bearer ${env:PIDGEON_API_KEY}" }，Cursor 便會從你的環境變數中填入它。

Codex、VS Code 和 Gemini CLI

對 Codex、VS Code 和 Gemini CLI，只要執行一個命令，就能將伺服器寫入用戶端自己的檔案：

npx -y @pidgeon-ai/mcp init --client codex    # ~/.codex/config.toml
npx -y @pidgeon-ai/mcp init --client vscode   # .vscode/mcp.json
npx -y @pidgeon-ai/mcp init --client gemini   # .gemini/settings.json

若未設定金鑰，命令只會寫入 URL，並由用戶端讓你登入。若已設定 PIDGEON_API_KEY，命令會先檢查金鑰，再讓用戶端從該變數讀取金鑰（Codex、Gemini CLI），或提示你輸入一次（VS Code），因此金鑰不會寫入檔案。它會保留現有內容，包括註解；修改檔案前會先複製到 <file>.bak；第二次執行時不會做任何事；只有使用 --force 時，才會取代不同的 pidgeon 項目。使用 --scope user 或 --scope project 可選擇另一個檔案；--print 則不會寫入任何內容。

或者安裝套件

PIDGEON_API_KEY=pgn_live_… npx -y @pidgeon-ai/mcp init

它會先用 API 驗證金鑰，再寫入任何內容，並告訴你金鑰能存取哪些地址——這是 JSON 區塊無法回答的唯一問題；若不先確認，這個問題就會以模型悄悄收到錯誤、而你完全看不到的方式浮現。接著，它會在目前目錄中寫入 .mcp.json，並印出寫入的內容。它絕不會取代已存在的項目：--force 才會執行取代，而 --print 會顯示設定但不寫入任何內容；如果你的用戶端將設定檔放在其他位置，這正是你需要的選項。

金鑰會透過環境變數參照，而不會寫入檔案，因此設定檔可以提交，憑證則不會：

{
"mcpServers": {
  "pidgeon": {
    "command": "npx",
    "args": ["-y", "@pidgeon-ai/mcp"],
    "env": { "PIDGEON_API_KEY": "${PIDGEON_API_KEY}" }
  }
}
}

Claude Desktop 或任何其他 MCP 用戶端都可以使用相同的區塊。若要直接執行伺服器（主要適合用來觀察啟動過程）：

PIDGEON_API_KEY=pgn_live_… npx -y @pidgeon-ai/mcp

PIDGEON_BASE_URL 可將它指向 production 以外的位置；只有在你自行執行 Pidgeon 時才有用。

金鑰就是全部的存取控制

這會將 API 金鑰交給模型——由你建立的金鑰，或你透過登入授予的金鑰。套件不會決定可以存取哪些內容：完全由金鑰本身的權限上限和授予它的地址決定，並在伺服器端執行，與其他呼叫者完全相同。這裡沒有第二套規則可讓你弄錯。

因此，請提供 agent 所需的最低權限金鑰。在 read 建立的金鑰，無論收件匣授予它多大的權限，都永遠無法傳送郵件——請參閱驗證，了解金鑰的存取範圍代表什麼，以及如何縮小範圍。只負責分類的 agent 應持有只能讀取的金鑰；如此一來，它是否可能寄出令人尷尬的內容，就不再是提示詞的問題。

金鑰的存取範圍是授予它的地址快照，因此金鑰建立後新增的地址不會包含在其中。

它提供的功能

共 42 項，從伺服器自己的清單讀取，因此本頁不會落後於伺服器：

工具	功能	Endpoint
list_addresses	此憑證可存取的地址。	GET /identities
create_address	建立供 agent 使用的地址。	POST /identities
get_address	依 id 查詢單一地址。	GET /identities/{id}
list_threads	單一地址中的對話，依最新到最舊排序。	GET /threads
get_thread	依 id 查詢單一對話。	GET /threads/{id}
list_messages	單一對話中的訊息，依最舊到最新排序——回覆前應先閱讀的內容。	GET /messages
search_messages	在此憑證可存取的所有地址中進行全文搜尋，並依相關性排序。	GET /messages/search
send_message	從此憑證獲准代表其傳送郵件的地址寄信。	POST /messages
get_message	依 id 查詢單一訊息，包含內文、我們保留的標頭，以及寄件網域的記錄所證明的內容——authentication.spf\、.dkim\、.dmarc\；null 表示未回報，而非驗證失敗。	GET /messages/{id}
await_message	等待訊息送達某個地址——例如提交註冊表單後——並回傳訊息及 extracted.codes\ 和 extracted.links\：最可能的驗證碼和確認連結會排在前面。	GET /messages/await
reply_to_message	收件者、主旨和郵件串會從要回覆的訊息中讀取，因此你只需提供文字。	POST /messages/{id}/reply
forward_message	將一封訊息及其附件轉寄給原本未列為收件者的人，並從收到該訊息的地址寄出。	POST /messages/{id}/forward
create_draft	撰寫但不寄出訊息，留給人員閱讀並寄送——若有人要求你準備回覆以供核准，請使用此功能。	POST /drafts
get_draft_approval	依其 draft\_id\ 查詢暫緩寄送的狀態：在有人於儀表板核准或拒絕前為 pending\；之後會變成 approved\（表示已寄出，而 message\_id\ 是該訊息）、rejected\，或在 24 小時內無人決定時變成 expired\。	GET /drafts/{id}/approval
list_drafts	列出單一地址的所有草稿，依最新到最舊排序，並包含收件者和內文，方便你稍後回來完成草稿。	GET /drafts
get_draft	依 id 查詢單一草稿：寄件者、收件者、主旨、文字和附件。	GET /drafts/{id}
update_draft	只變更你傳入的欄位，其餘欄位保持不變；null\ 可清除主旨或文字。	PATCH /drafts/{id}
delete_draft	刪除單一草稿；若已排程寄送，也會取消寄送。	DELETE /drafts/{id}
read_attachment	讀取單一附件的文字內容——CSV、log、JSON、行事曆檔案、PDF、Word .docx\ 或 Excel .xlsx\。	GET /attachments/{id}/text
update_thread	查詢對話由誰負責，以及目前進度。	PATCH /threads/{id}
update_message	為訊息加上星號，或將其移至 archive\、spam\ 或 trash\。	PATCH /messages/{id}
list_send_rules	查詢單一地址的允許清單和封鎖清單，以及其所依據的寄送政策。	GET /identities/{id}/send-rules
list_receive_rules	決定哪些內容會送達單一地址的規則——依寄件者或網域拒收、標記為垃圾郵件、移至垃圾桶、封存或放入收件匣——以及其 receive\_policy\。	GET /identities/{id}/receive-rules
list_folders	列出單一地址的所有資料夾及其計數。	GET /mailboxes
list_folder	列出單一地址的某個資料夾，依最新到最舊排序，每列一個對話——list\_threads\ 會告訴你有哪些對話，而此功能會告訴你它們存放在哪裡，以及在清單中的樣貌。	GET /mailboxes/{folder}
list_changes	列出自某個 sync\_cursor\ 以來，單一收件匣中所有變動的內容，包括新收到的郵件，讓長時間執行的 agent 不必重新讀取整個資料夾來尋找一封新訊息。	GET /mailboxes/changes
list_events	列出此憑證可存取的所有地址中的每個事件——收到、寄出、送達、退信和歸檔的郵件。	GET /events
list_labels	標籤屬於地址，而非工作區，因此三個地址上同名的標籤，實際上是三個各有不同 id 的標籤。	GET /labels
create_label	查詢單一地址上的標籤。	POST /labels
apply_label	標籤必須屬於對話所在的同一個地址——使用該地址的 list\_labels\ 即可取得正確的 id。	POST /threads/{id}/labels
remove_label	從單一對話中移除一個標籤。	DELETE /threads/{id}/labels
list_pods	pod 是用來容納你自有客戶的容器：其中包含地址和網域，且**從中寄出的郵件會使用自己的寄件信譽**，因此一位客戶不會損害另一位客戶的郵件送達率。	GET /pods
create_pod	用來容納單一客戶的容器，並擁有自己的寄件信譽。	POST /pods
get_metrics	在 days\ 的時間範圍內統計寄出、送達、退信、拒收、投訴、收到和垃圾郵件——資料來自事件記錄，因此也包含服務供應商事後回報的結果。	GET /metrics
get_calendar	查詢單一地址的行事曆，依地址的 id\ 顯示：預設時區及事件數量。	GET /identities/{id}/calendar
update_calendar	查詢未指定時區的事件所使用的時區，格式為 IANA 名稱，例如 Europe/Lisbon\。	PATCH /identities/{id}/calendar
get_agenda	查詢地址行事曆中介於 after\ 和 before\ 之間的內容（ISO 8601 日期時間），依開始時間排序；週期性事件的每個日期都會各自列出。	GET /identities/{id}/calendar/agenda
get_calendar_event	依 eventId\ 查詢地址 id\ 行事曆中的單一事件：時間、說明、地點、週期，以及與會者和他們的回覆。	GET /identities/{id}/calendar/events/{eventId}
create_calendar_event	在地址 id\ 的行事曆中新增事件。	POST /identities/{id}/calendar/events
update_calendar_event	變更單一行事曆事件：只修改你傳入的欄位，其餘欄位保持不變。	PATCH /identities/{id}/calendar/events/{eventId}
delete_calendar_event	從地址 id\ 的行事曆中移除事件。	DELETE /identities/{id}/calendar/events/{eventId}
respond_to_invitation	依訊息的 id\ 回覆以郵件形式收到的會議邀請：accepted\、declined\ 或 tentative\，並可選擇提供 comment\。	POST /messages/{id}/invitation/respond

每項工具都對應到旁邊的 reference 中的 endpoint，並遵循相同的拒絕規則。金鑰無權使用的工具會像 API 一樣失敗，並回傳 API 原本會使用的句子。

除非指定單一地址，否則搜尋會涵蓋金鑰可存取的所有地址；每筆結果都會指出找到內容的地址。

它不是什麼

它不是 agent 執行環境，也不會替你做任何決定。Pidgeon 不會對你執行哪個模型或模型可以得出什麼結論表達意見——這與對話串與交接對產品其他部分所採取的立場相同。如果 agent 卡住了，將對話交給人員處理是對話串的狀態，而不是此套件的功能。