Mailtrap MCP Server

MCP Mailtrap 伺服器

一個 MCP 伺服器，提供透過 Mailtrap 在沙箱中發送和測試的工具。

先決條件

在使用此 MCP 伺服器之前，您需要：

1. 建立 Mailtrap 帳戶
2. 驗證您的網域
3. 從 Mailtrap API 設定 取得您的 API 權杖
4. 從 Mailtrap 帳戶管理 取得您的帳戶 ID

必要的環境變數：

• MAILTRAP_API_TOKEN - 所有功能皆需要
• MAILTRAP_ACCOUNT_ID - 範本、統計資料、電子郵件記錄、沙箱清單/顯示以及發送網域需要。僅在 send-email 和 send-sandbox-email 為選用。

選用（可改為作為工具參數傳遞）：

• DEFAULT_FROM_EMAIL - 當未提供 from 給 send-email 或 send-sandbox-email 時的預設寄件者電子郵件。可透過 from 參數在每次呼叫時切換寄件者。
• MAILTRAP_TEST_INBOX_ID - 當未提供 test_inbox_id 時，沙箱工具的預設測試收件匣 ID。可透過 test_inbox_id 參數在每次呼叫時切換收件匣。
• MAILTRAP_SANDBOX_ID - 當未提供 sandbox_id 時，沙箱工具的預設沙箱 ID。可透過 sandbox_id 參數在每次呼叫時切換沙箱。
• MAILTRAP_ORGANIZATION_ID - 組織工具（list-sub-accounts、create-sub-account）需要。
• MAILTRAP_ORGANIZATION_API_TOKEN - 組織範圍的 API 權杖。組織工具需要（與 MAILTRAP_API_TOKEN 分開）。

快速安裝

Smithery CLI

Smithery 是一個適用於所有 AI 客戶端的 MCP 伺服器登錄安裝程式和管理器。

npx @smithery/cli install mailtrap

Smithery 會自動處理客戶端設定，並提供互動式設定流程。這是在本機開始使用 MCP 伺服器最簡單的方式。

設定

Claude Desktop

使用 MCPB 安裝 Mailtrap 伺服器。您可以在 Releases 中找到這些檔案。
下載 .MCPB 檔案並開啟它。如果您有 Claude Desktop，它將會開啟並建議進行設定。

Claude Desktop 或 Cursor

新增以下設定：

{
  "mcpServers": {
    "mailtrap": {
      "command": "npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

如果您使用 asdf 管理 Node.js，則必須使用執行檔的絕對路徑（以 Mac 為例）

{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users/<username>/.asdf/shims/npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "PATH": "/Users/<username>/.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
        "ASDF_DATA_DIR": "/Users/<username>/.asdf",
        "ASDF_NODEJS_VERSION": "20.6.1",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Claude Desktop 設定檔位置

Mac：~/Library/Application Support/Claude/claude_desktop_config.json

Windows：%APPDATA%\Claude\claude_desktop_config.json

Cursor 設定檔位置

Mac：~/.cursor/mcp.json

Windows：%USERPROFILE%\.cursor\mcp.json

VS Code

手動更改設定

在命令面板中執行：Preferences: Open User Settings (JSON)

然後，在設定檔中，新增以下設定：

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "npx",
        "args": ["-y", "mcp-mailtrap"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "[email protected]",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

[!TIP] 更改 "env" 區段後，別忘了重新啟動您的 MCP 伺服器。

MCP Bundle (MCPB)

為了在支援 MCP Bundles 的主機中輕鬆安裝，您可以發佈一個 .mcpb 捆綁檔案。

# Build TypeScript and pack the MCPB bundle
npm run mcpb:pack

# Inspect bundle metadata
npm run mcpb:info

# Sign the bundle for distribution (optional)
npm run mcpb:sign

這會使用儲存庫 manifest.json 和 dist/ 中的建置成品來建立 mailtrap-mcp.mcpb。

使用方式

設定完成後，您可以要求代理程式發送電子郵件和管理範本，例如：

電子郵件發送操作：

• "發送一封電子郵件到 [email protected]，主旨為 '明天會議'，並附上關於我們即將舉行的會議的友善提醒。"
• "寄信給 [email protected] 關於專案更新，並副本給團隊 [email protected]"
• "使用變數 { name: 'Alex' } 將歡迎範本（uuid b81aabcd-1a1e-41cf-91b6-eca0254b3d96）發送給 [email protected]"
• "發送一封沙箱電子郵件到 [email protected]，主旨為 '測試範本'，以預覽我們的歡迎電子郵件外觀"

電子郵件記錄（除錯傳遞）：

• "列出我最近發送的電子郵件記錄"
• "顯示發送給 [email protected] 的電子郵件記錄"
• "取得 ID 為 abc-123-uuid 的電子郵件記錄訊息，以檢查傳遞狀態"

發送統計資料：

• "取得 2025 年 1 月的發送統計資料"
• "顯示上個月按網域細分的傳遞率"
• "從 2025-01-01 到 2025-01-31，我的電子郵件統計資料按類別為何？"

沙箱操作：

• "從我的沙箱收件匣取得所有訊息"
• "顯示第一頁的沙箱訊息"
• "在我的沙箱收件匣中搜尋包含 'test' 的訊息"
• "顯示 ID 為 5159037506 的沙箱訊息詳細資料"

範本操作：

• "列出我 Mailtrap 帳戶中的所有電子郵件範本"
• "建立一個名為 '歡迎電子郵件' 的新電子郵件範本，主旨為 '歡迎來到我們的平台！'"
• "更新 ID 為 12345 的範本，將主旨更改為 '已更新的歡迎訊息'"
• "刪除 ID 為 67890 的範本"

發送網域：

• "列出我的發送網域"
• "取得 ID 為 3938 的發送網域"
• "為 example.com 建立一個發送網域"
• "刪除發送網域 3938"
• "取得發送網域 3938 及其 DNS 設定說明"

可用工具

send-email

透過 Mailtrap 發送交易電子郵件。支援兩種互斥模式 — 內嵌內容（subject + text/html）或 基於範本（template_uuid）。

參數：

• from（選用）：寄件者，格式為電子郵件字串或 { email, name? }。若未提供，則使用 DEFAULT_FROM_EMAIL。
• to（選用）：收件者 — 單一電子郵件/{ email, name? } 或陣列。若提供 cc 或 bcc 則為選用；to / cc / bcc 中至少需包含一個收件者。
• cc（選用）：副本收件者陣列（每個為電子郵件字串或 { email, name? }）。
• bcc（選用）：密件副本收件者陣列（每個為電子郵件字串或 { email, name? }）。
• subject（條件式）：電子郵件主旨行。內嵌發送時為必要；設定 template_uuid 時必須省略。
• text（條件式）：電子郵件內文文字。內嵌發送時為必要（與 html 一起或代替它）；設定 template_uuid 時必須省略。
• html（條件式）：電子郵件內文的 HTML 版本。內嵌發送時為必要（與 text 一起或代替它）；設定 template_uuid 時必須省略。
• category（選用）：用於追蹤和分析的電子郵件類別。設定 template_uuid 時必須省略。
• template_uuid（選用）：使用 Mailtrap 電子郵件範本而非內嵌內容。設定時，subject / text / html / category 必須省略（依據 Mailtrap API）。
• template_variables（選用）：代入 template_uuid 所參考範本中的變數物件。僅允許與 template_uuid 一起使用。

batch-send-transactional-email

在一個 Mailtrap API 呼叫中發送一批交易電子郵件（預設發送串流）。共用欄位放在 base 上；每個收件者的覆寫放在 requests[] 中。每個請求必須透過 to、cc 或 bcc 包含至少一個收件者。與 send-email 相同的內嵌與範本互斥規則 — 在合併基礎與每個請求後檢查。

參數：

• base（選用）：包含批次中共用欄位的物件。
  • from（選用）：寄件者，格式為電子郵件字串或 { email, name? }。退回使用 DEFAULT_FROM_EMAIL。
  • reply_to（選用）：回覆地址。
  • subject / text / html / category（選用，內嵌模式）：每個請求的預設內容。
  • template_uuid / template_variables（選用，範本模式）：預設範本 + 變數。與內嵌欄位互斥。
  • custom_variables（選用）：預設自訂變數（字串值）。
  • headers（選用）：預設自訂標頭。
• requests（必要）：非空的每個收件者訊息陣列。每個條目包含：
  • to（選用）：收件者 — 字串、{ email, name? } 或陣列。若提供 cc 或 bcc 則為選用；to / cc / bcc 中至少需包含一個收件者。
  • cc、bcc、reply_to（選用）。
  • 內嵌（subject/text/html/category）或範本（template_uuid/template_variables）覆寫；任何省略的欄位會退回使用相符的 base 值。
  • custom_variables、headers（選用）。

batch-send-bulk-email

透過 Mailtrap 的大量串流 API 發送一批大量電子郵件。與 batch-send-transactional-email 相同的 base + requests[] 形狀、驗證和內嵌與範本規則 — 唯一的區別是此工具將呼叫路由到大量端點而非交易端點。請參閱上述參數。

list-email-logs

列出已發送的電子郵件記錄（傳遞歷史記錄），可選擇分頁和篩選。用於從 IDE 除錯傳遞問題。

參數：

• search_after（選用）：來自前一個回應的 next_page_cursor 的分頁游標
• sent_after（選用）：ISO 8601 日期/時間；僅顯示在此時間之後發送的記錄
• sent_before（選用）：ISO 8601 日期/時間；僅顯示在此時間之前發送的記錄
• from_email（選用）：按寄件者電子郵件篩選；與 from_operator 一起使用（預設：ci_equal）
• to_email（選用）：按收件者電子郵件篩選；與 to_operator 一起使用（預設：ci_equal）
• status（選用）：按傳遞狀態篩選：delivered、not_delivered、enqueued、opted_out；與 status_operator 一起使用（預設：equal）
• subject（選用）：按電子郵件主旨篩選；與 subject_operator 一起使用（預設：ci_contain）。使用 subject_operator：empty/not_empty 來按主旨是否存在篩選。
• sending_domain_id（選用）：按發送網域 ID（數字）篩選；與 sending_domain_id_operator 一起使用（預設：equal）
• sending_stream（選用）：按串流篩選：transactional 或 bulk；與 sending_stream_operator 一起使用（預設：equal）
• events（選用）：按事件類型篩選：delivery、open、click、bounce、spam、unsubscribe、soft_bounce、reject、suspension；與 events_operator 一起使用（include_event / not_include_event）
• clicks_count / opens_count（選用）：按點擊/開啟次數篩選；與 *_operator 一起使用：equal、greater_than、less_than
• client_ip / sending_ip（選用）：按 IP 篩選；與 *_operator 一起使用：equal、not_equal、contain、not_contain
• email_service_provider_response（選用）：按提供者回應文字篩選；與 *_operator 一起使用（ci_contain 等）
• email_service_provider（選用）：按提供者（精確）篩選；與 *_operator 一起使用：equal、not_equal
• recipient_mx（選用）：按收件者 MX 篩選；與 recipient_mx_operator 一起使用（ci_contain 等）
• category（選用）：按電子郵件類別篩選；與 category_operator 一起使用：equal、not_equal

所有參數皆為選用。

get-email-log-message

透過 ID（UUID）取得單一電子郵件記錄訊息：可讀的摘要（寄件者、收件者、主旨、發送時間、狀態、類別、串流、互動、傳遞內容），然後是詳細的事件歷史記錄。可選地，使用 include_content: true，當 Mailtrap 公開原始訊息 URL 時，您也可以載入並顯示訊息內文（HTML 和純文字）。

參數：

• message_id（必要）：電子郵件記錄訊息的 UUID（來自發送回應或 list-email-logs）。使用 list-email-logs 來尋找訊息 ID。
• include_content（選用）：當設為 true 時，會擷取原始 EML（如果 raw_message_url 可用），並附加解析後的 HTML 和純文字內文區段，類似於 show-sandbox-email-message。

get-sending-stats

取得日期範圍內的電子郵件發送統計資料（傳遞率、退信率、開啟率、點擊率、垃圾郵件率）。可選擇按網域、類別、電子郵件服務提供者或日期細分。無需離開編輯器即可檢查傳遞率。

參數：

• start_date（必填）：統計範圍的開始日期（YYYY-MM-DD）
• end_date（必填）：統計範圍的結束日期（YYYY-MM-DD）
• breakdown（選填）：統計資料的細分方式：aggregated（預設）、by_domain、by_category、by_email_service_provider 或 by_date
• sending_domain_ids（選填）：將結果限制在這些寄件網域 ID（整數陣列）
• sending_streams（選填）：限制為 transactional 和／或 bulk（字串陣列）
• categories（選填）：限制為這些電子郵件類別（字串陣列）
• email_service_providers（選填）：限制為這些提供者，例如 Google、Yahoo、Outlook（字串陣列）

create-template

在您的 Mailtrap 帳戶中建立新的電子郵件範本。

參數：

• name（必填）：範本名稱
• subject（必填）：電子郵件主旨行
• html（或 text 為必填）：範本的 HTML 內容
• text（或 html 為必填）：範本的純文字版本
• category（選填）：範本類別（預設為「General」）

list-templates

列出您 Mailtrap 帳戶中的所有電子郵件範本。

參數：

• 無需參數

get-template

依 ID 取得單一電子郵件範本，包括主旨、類別和 HTML／文字內文。

參數：

• template_id（必填）：要擷取的範本 ID

update-template

更新現有的電子郵件範本。

參數：

• template_id（必填）：要更新的範本 ID
• name（選填）：範本的新名稱
• subject（選填）：新的電子郵件主旨行
• html（選填）：範本的新 HTML 內容
• text（選填）：範本的新純文字版本
• category（選填）：範本的新類別

[!NOTE] 呼叫 update-template 執行更新時，必須提供至少一個可更新欄位（名稱、主旨、html、文字或類別）。

delete-template

刪除現有的電子郵件範本。

參數：

• template_id（必填）：要刪除的範本 ID

send-sandbox-email

將電子郵件傳送到您的 Mailtrap 測試收件匣，用於開發和測試目的。這非常適合在不傳送給真實收件者的情況下測試電子郵件範本。支援與 send-email 相同的兩種模式 — 內嵌內容 或 基於範本（template_uuid）。

參數：

• test_inbox_id（選填）：Mailtrap 測試收件匣 ID。除非設定了 MAILTRAP_TEST_INBOX_ID，否則為必填；每次呼叫時傳遞以指定特定收件匣。
• from（選填）：寄件者，格式為電子郵件字串或 { email, name? }。若未提供，則使用 DEFAULT_FROM_EMAIL。
• to（選填）：收件者，格式為逗號分隔字串，或電子郵件字串／{ email, name? } 物件的陣列。若提供了 cc 或 bcc，則為選填；to／cc／bcc 中至少一個必須包含收件者。
• cc（選填）：副本收件者陣列（每個為電子郵件字串或 { email, name? }）。
• bcc（選填）：密件副本收件者陣列（每個為電子郵件字串或 { email, name? }）。
• subject（條件式）：電子郵件主旨行。內嵌傳送時為必填；設定 template_uuid 時必須省略。
• text（條件式）：電子郵件內文文字。內嵌傳送時為必填（與 html 一起或代替它）；設定 template_uuid 時必須省略。
• html（條件式）：電子郵件內文的 HTML 版本。內嵌傳送時為必填（與 text 一起或代替它）；設定 template_uuid 時必須省略。
• category（選填）：用於追蹤的電子郵件類別。設定 template_uuid 時必須省略。
• template_uuid（選填）：使用 Mailtrap 電子郵件範本而非內嵌內容。設定後，必須省略 subject／text／html／category。
• template_variables（選填）：變數物件，會替換到 template_uuid 所引用的範本中。僅允許與 template_uuid 一起使用。

[!NOTE] 對於沙箱工具，請在工具呼叫中提供 test_inbox_id，或設定 MAILTRAP_TEST_INBOX_ID 環境變數。您可以透過傳遞 test_inbox_id 在每次呼叫時切換收件匣。

get-sandbox-messages

從您的 Mailtrap 測試收件匣擷取郵件清單。用於在測試期間檢查沙箱中收到了哪些電子郵件。

參數：

• page（選填）：分頁的頁碼（最小值：1）
• last_id（選填）：使用最後一則郵件 ID 進行分頁。傳回指定郵件 ID 之後的郵件（最小值：1）
• search（選填）：用於篩選郵件的搜尋查詢

[!NOTE] 所有參數皆為選填。若未提供任何參數，將傳回收件匣的第一頁郵件。使用 page 進行傳統分頁，使用 last_id 進行游標式分頁，或使用 search 按內容篩選郵件。

show-sandbox-email-message

顯示 Mailtrap 測試收件匣中特定電子郵件的詳細資訊和內容，包括 HTML 和文字內文內容。

參數：

• message_id（必填）：要擷取的沙箱電子郵件 ID

[!NOTE] 先使用 get-sandbox-messages 取得郵件清單及其 ID，然後使用此工具檢視特定郵件的完整內容。

get-sandbox-project

依 ID 取得沙箱專案，包括其收件匣和電子郵件計數。

參數：

• project_id（必填）：要擷取的專案 ID

update-sandbox-project

重新命名現有的沙箱專案。

參數：

• project_id（必填）：要更新的專案 ID
• name（必填）：專案的新名稱（2–100 個字元）

list-sandboxes

列出 API 權杖可存取的所有沙箱，橫跨所有專案。

參數：

• 無需參數

mark-sandbox-as-read

將沙箱中的所有郵件標記為已讀。

參數：

• sandbox_id（必填）：要操作的沙箱 ID

reset-sandbox-credentials

重設沙箱的 SMTP 憑證。傳回新的使用者名稱／密碼。

參數：

• sandbox_id（必填）：要操作的沙箱 ID

enable-sandbox-email-address

啟用沙箱的「透過電子郵件接收」地址（開啟 Mailtrap 地址，該地址會透過 SMTP 將郵件傳遞到沙箱）。

參數：

• sandbox_id（必填）：要操作的沙箱 ID

reset-sandbox-email-address

為沙箱產生新的「透過電子郵件接收」地址。

參數：

• sandbox_id（必填）：要操作的沙箱 ID

forward-sandbox-message

將沙箱郵件轉寄到外部電子郵件地址。會計入您的每月轉寄配額。

參數：

• sandbox_id（選填）：沙箱 ID。預設回退到 MAILTRAP_SANDBOX_ID。
• message_id（必填）：要轉寄的沙箱郵件 ID
• email（必填）：要將郵件轉寄到的電子郵件地址

update-sandbox-message

將沙箱郵件標記為已讀或未讀。

參數：

• sandbox_id（選填）：沙箱 ID。預設回退到 MAILTRAP_SANDBOX_ID。
• message_id（必填）：要更新的沙箱郵件 ID
• is_read（必填）：true 標記為已讀，false 標記為未讀

delete-sandbox-message

刪除單一沙箱郵件。

參數：

• sandbox_id（選填）：沙箱 ID。預設回退到 MAILTRAP_SANDBOX_ID。
• message_id（必填）：要刪除的沙箱郵件 ID

get-sandbox-message-spam-score

取得沙箱郵件的 SpamAssassin 垃圾郵件報告（分數、規則、完整報告）。作為 show-sandbox-email-message 上 include_spam_report: true 的獨立替代方案。

參數：

• sandbox_id（選填）：沙箱 ID。預設回退到 MAILTRAP_SANDBOX_ID。
• message_id（必填）：沙箱郵件 ID

get-sandbox-message-html-analysis

取得沙箱郵件的 HTML 分析報告（用戶端相容性分數、有問題的元素）。作為 show-sandbox-email-message 上 include_html_analysis: true 的獨立替代方案。

參數：

• sandbox_id（選填）：沙箱 ID。預設回退到 MAILTRAP_SANDBOX_ID。
• message_id（必填）：沙箱郵件 ID

get-sandbox-message-headers

取得沙箱郵件的已解析郵件標頭。

參數：

• sandbox_id（選填）：沙箱 ID。預設回退到 MAILTRAP_SANDBOX_ID。
• message_id（必填）：沙箱郵件 ID

get-sandbox-message-html

取得沙箱郵件的渲染後 HTML 內文。

參數：

• sandbox_id（選填）：沙箱 ID。預設回退到 MAILTRAP_SANDBOX_ID。
• message_id（必填）：沙箱郵件 ID

get-sandbox-message-text

取得沙箱郵件的純文字內文。

參數：

• sandbox_id（選填）：沙箱 ID。預設回退到 MAILTRAP_SANDBOX_ID。
• message_id（必填）：沙箱郵件 ID

get-sandbox-message-raw

取得沙箱郵件的原始 MIME 格式郵件（標頭 + 內文）。

參數：

• sandbox_id（選填）：沙箱 ID。預設回退到 MAILTRAP_SANDBOX_ID。
• message_id（必填）：沙箱郵件 ID

get-sandbox-message-eml

取得渲染為 EML 檔案酬載的郵件（適合附加到工單或匯入其他郵件用戶端）。

參數：

• sandbox_id（選填）：沙箱 ID。預設回退到 MAILTRAP_SANDBOX_ID。
• message_id（必填）：沙箱郵件 ID

get-sandbox-message-html-source

取得沙箱郵件的未渲染 HTML 原始碼（在任何 Mailtrap 端轉換（如 CID 連結重寫）之前的 HTML）。

參數：

• sandbox_id（選填）：沙箱 ID。預設回退到 MAILTRAP_SANDBOX_ID。
• message_id（必填）：沙箱郵件 ID

list-sandbox-attachments

列出沙箱郵件上的所有附件（檔案名稱、內容類型、大小、下載路徑）。

參數：

• sandbox_id（選填）：沙箱 ID。預設回退到 MAILTRAP_SANDBOX_ID。
• message_id（必填）：沙箱郵件 ID

get-sandbox-attachment

取得單一附件的中繼資料和下載 URL。

參數：

• sandbox_id（選填）：沙箱 ID。預設回退到 MAILTRAP_SANDBOX_ID。
• message_id（必填）：包含附件的沙箱郵件 ID
• attachment_id（必填）：要擷取的附件 ID

list-sending-domains

列出寄件網域及其 DNS 驗證狀態。

參數：

• 無需參數

get-sending-domain

依 ID 取得寄件網域及其驗證狀態（包括 DNS 記錄）。可選擇透過將 include_setup_instructions 設為 true 來包含 DNS 設定指示。

參數：

• sending_domain_id（必填）：寄件網域 ID
• include_setup_instructions（選填）：若為 true，則在回應中附加 DNS 設定指示。預設：false

create-sending-domain

建立新的寄件網域。建立後，請新增 DNS 記錄以驗證網域（使用 get-sending-domain 並搭配 include_setup_instructions: true 來查看記錄）。

參數：

• domain_name（必填）：網域名稱（例如 example.com）

delete-sending-domain

刪除寄件網域。

參數：

• sending_domain_id（必填）：要刪除的寄件網域 ID

send-sending-domain-setup-instructions

將寄件網域的 DNS 設定指示透過電子郵件傳送到指定地址。適用於將 DNS 記錄轉寄給 DevOps 團隊成員。

參數：

• sending_domain_id（必填）：寄件網域 ID
• email（必填）：要接收 DNS 設定指示的電子郵件地址

list-suppressions

列出或搜尋抑制項目（硬退信、垃圾郵件投訴、取消訂閱、手動匯入）。每次呼叫最多傳回 1000 筆結果。

參數：

• email（選用）：電子郵件篩選條件。僅傳回符合此地址的封鎖記錄。

delete-suppression

依 ID 刪除封鎖記錄。Mailtrap 將恢復傳送郵件至此電子郵件地址，除非該地址再次被封鎖。

參數：

• suppression_id（必要）：要刪除的封鎖記錄 ID

list-webhooks

列出帳戶中設定的所有 webhook。以 JSON 格式傳回完整的 webhook 記錄。

參數：

• 無需參數

get-webhook

依 ID 取得單一 webhook。以 JSON 格式傳回完整的 webhook 記錄。注意：此處不會傳回 signing_secret — 它僅在 create-webhook 的回應中提供。

參數：

• webhook_id（必要）：要擷取的 webhook ID

create-webhook

建立 webhook。回應中包含用於驗證 webhook 酬載簽章的 signing_secret — 此密鑰僅在建立時傳回，因此請立即儲存。若遺失，請重新建立 webhook。

參數：

• url（必要）：Mailtrap 將向其 POST webhook 事件的 URL
• webhook_type（必要）："email_sending" 或 "audit_log"
• active（選用，布林值）：預設為 true
• payload_format（選用）："json" 或 "jsonlines"。預設為 "json"
• sending_stream（選用，僅限 email_sending）："transactional" 或 "bulk"
• event_types（選用，僅限 email_sending）：包含 delivery、soft_bounce、bounce、suspension、unsubscribe、open、spam_complaint、click、reject 的陣列
• domain_id（選用，僅限 email_sending）：要將此 webhook 範圍限定到的寄件網域 ID

update-webhook

更新 webhook 的可變更欄位。webhook_type、sending_stream 和 domain_id 在建立後無法變更 — 若需變更這些項目，請重新建立 webhook。

參數：

• webhook_id（必要）：要更新的 webhook ID
• url（選用）：新的 webhook URL
• active（選用，布林值）：啟用或停用 webhook
• payload_format（選用）："json" 或 "jsonlines"
• event_types（選用，僅限 email_sending）：包含 delivery、soft_bounce、bounce、suspension、unsubscribe、open、spam_complaint、click、reject 的陣列

delete-webhook

依 ID 永久刪除 webhook。傳回已刪除的 webhook 記錄。

參數：

• webhook_id（必要）：要刪除的 webhook ID

get-contact

依 ID 或電子郵件取得聯絡人。傳回完整的聯絡人記錄（清單成員資格、狀態、自訂欄位）。

參數：

• contact_identifier（必要）：聯絡人 ID 或電子郵件地址

create-contact

建立新聯絡人。

參數：

• email（必要）：電子郵件地址
• fields（選用）：以合併標籤為索引鍵的自訂欄位值（例如 first_name）。可為字串、數字或布林值
• list_ids（選用）：要將此聯絡人訂閱到的聯絡人清單 ID
• unsubscribed（選用，布林值）：以 unsubscribed 狀態建立聯絡人

update-contact

更新由 ID 或電子郵件識別的現有聯絡人。list_ids 會取代聯絡人的完整成員資格集合；list_ids_included/list_ids_excluded 則在不影響其餘項目的情況下新增/移除。

參數：

• contact_identifier（必要）：聯絡人 ID 或電子郵件
• email（選用）：新的電子郵件地址
• fields（選用）：以合併標籤為索引鍵的自訂欄位值
• list_ids（選用）：以此確切清單取代成員資格集合
• list_ids_included（選用）：要新增的清單 ID（附加性質）
• list_ids_excluded（選用）：要移除的清單 ID
• unsubscribed（選用，布林值）：設為 unsubscribed（true）或 subscribed（false）

delete-contact

依 ID 或電子郵件永久刪除聯絡人。當 API 回應包含已刪除的聯絡人記錄時傳回該記錄；否則傳回確認酬載。

參數：

• contact_identifier（必要）：聯絡人 ID 或電子郵件

create-contact-event

針對聯絡人（依 ID 或電子郵件）記錄聯絡人事件。用於觸發聯絡人清單自動化流程。

參數：

• contact_identifier（必要）：聯絡人 ID 或電子郵件
• name（必要）：事件名稱（需與自動化觸發條件相符）
• params（必要）：任意索引鍵/值配對的物件。值可為字串、數字、布林值或 null

list-contact-lists

列出帳戶的所有聯絡人清單。

參數：

• 無需參數

get-contact-list

依 ID 取得聯絡人清單。

參數：

• list_id（必要）：要擷取的聯絡人清單 ID

create-contact-list

建立新的聯絡人清單。

參數：

• name（必要）：新清單的名稱

update-contact-list

重新命名現有的聯絡人清單。

參數：

• list_id（必要）：聯絡人清單的 ID
• name（必要）：清單的新名稱

delete-contact-list

依 ID 永久刪除聯絡人清單。

參數：

• list_id（必要）：要刪除的聯絡人清單 ID

list-contact-fields

列出帳戶的所有聯絡人欄位定義。

參數：

• 無需參數

get-contact-field

依 ID 取得聯絡人欄位定義。

參數：

• field_id（必要）：聯絡人欄位的 ID

create-contact-field

建立新的聯絡人欄位定義。merge_tag 在帳戶內必須是唯一的，並用作範本變數中的佔位符名稱。

參數：

• name（必要）：顯示名稱（例如「名字」）
• merge_tag（必要）：唯一的佔位符名稱（例如 first_name）
• data_type（必要）：text、number、boolean、date 其中之一

update-contact-field

更新聯絡人欄位定義。可變更 name、merge_tag 和 data_type 的任意組合。

參數：

• field_id（必要）：聯絡人欄位的 ID
• name（選用）：新的顯示名稱
• merge_tag（選用）：新的合併標籤（必須保持唯一）
• data_type（選用）：text、number、boolean、date 其中之一

delete-contact-field

依 ID 永久刪除聯絡人欄位定義。

參數：

• field_id（必要）：要刪除的聯絡人欄位 ID

create-contact-import

批次匯入聯絡人。傳回匯入作業記錄；使用 get-contact-import 查詢其狀態。

參數：

• contacts（必要）：聯絡人條目陣列。每個條目需要：
  • email（必要）：聯絡人電子郵件地址
  • fields（選用）：以合併標籤為索引鍵的自訂欄位值（字串或數字值）
  • list_ids_included（選用）：要將聯絡人新增至其中的清單 ID
  • list_ids_excluded（選用）：要從中移除聯絡人的清單 ID

get-contact-import

取得聯絡人匯入作業的狀態（已建立/已開始/已完成/已失敗），包含已建立/已更新/超出限制的計數。

參數：

• import_id（必要）：聯絡人匯入作業的 ID

create-contact-export

匯出符合一組 AND 組合篩選條件的聯絡人。傳回匯出作業記錄；使用 get-contact-export 查詢狀態，以便在 status 為 finished 時擷取下載 URL。

參數：

• filters（必要）：篩選器物件陣列。每個物件包含：
  • name（必要）：要篩選的欄位（list_id、subscription_status、email 等）
  • operator（必要）：equal、not_equal、contains、not_contains、is_empty、is_not_empty 其中之一
  • value（必要）：比較值（字串、數字、布林值或陣列）

get-contact-export

取得聯絡人匯出作業的狀態。一旦 status 為 finished，url 欄位將包含 CSV 下載連結。

參數：

• export_id（必要）：聯絡人匯出作業的 ID

list-accounts

列出目前 API 權杖可存取的 Mailtrap 帳戶，以及每個帳戶的存取層級。

參數：

• 無需參數

get-billing-usage

取得帳戶目前計費週期的使用情況：寄件和測試方案、限制以及目前用量計數。

參數：

• 無需參數

list-account-accesses

列出帳戶的帳戶存取權（使用者、邀請、API 權杖）。可選的篩選條件能將結果限縮至特定資源。需要帳戶管理員/擁有者權限。

參數：

• domain_uuids（選用）：依寄件網域 UUID 篩選（字串陣列）
• inbox_ids（選用）：依沙箱收件匣 ID 篩選（字串陣列）
• project_ids（選用）：依沙箱專案 ID 篩選（字串陣列）

remove-account-access

依 ID 移除帳戶存取權。對於 User 規範器，這會撤銷其權限；對於 Invite 或 ApiToken 規範器，則會完全移除該規範器。需要管理員/擁有者權限。

參數：

• account_access_id（必要）：要移除的存取記錄 ID

get-permission-resources

取得 API 權杖具有管理員存取權的所有資源（收件匣、專案、網域、帳單、帳戶），並按階層巢狀排列。

參數：

• 無需參數

bulk-update-permissions

批次建立、更新或刪除單一帳戶存取權的權限。現有的 (resource_type, resource_id) 配對會被更新；新的配對會被建立。在條目上設定 destroy: true 即可將其移除。

參數：

• account_access_id（必要）：目標帳戶存取權 ID
• permissions（必要）：權限條目陣列。每個條目包含：
  • resource_id（必要）：資源 ID（數字或字串）
  • resource_type（必要）：account、project、inbox、domain、billing 其中之一
  • access_level（選用）：admin/100 或 viewer/10
  • destroy（選用，布林值）：設為 true 時，移除此權限而非建立/更新它

list-api-tokens

列出帳戶的所有 API 權杖。

參數：

• 無需參數

create-api-token

建立新的 API 權杖。回應中包含密鑰 token 值 — 這是唯一一次傳回完整權杖，因此請立即儲存。若遺失，請重新建立權杖。

參數：

• name（必要）：權杖的顯示名稱
• resources（選用）：要將權杖範圍限定到的資源權限陣列。每個條目包含：
  • resource_type（必要）：account、project、inbox、domain、billing 其中之一
  • resource_id（必要）：資源的 ID
  • access_level（必要）：100（管理員）或 10（檢視者）

get-api-token

依 ID 取得 API 權杖。僅傳回中繼資料 — 此處不會傳回密鑰權杖值（僅來自 create-api-token / reset-api-token）。

參數：

• api_token_id（必要）：API 權杖的 ID

reset-api-token

依 ID 重設（輪替）API 權杖。回應中包含新的密鑰 token 值 — 僅在此呼叫時傳回，因此請立即儲存。先前的權杖將失效。

參數：

• api_token_id（必要）：要重設的 API 權杖 ID

delete-api-token

依 ID 永久刪除 API 權杖。刪除後，該權杖將無法再進行驗證。

參數：

• api_token_id（必要）：要刪除的 API 權杖 ID

list-sub-accounts

列出組織中的子帳戶。需要 MAILTRAP_ORGANIZATION_ID 環境變數和子帳戶管理權限。

參數：

• 無需參數

create-sub-account在組織下建立新的子帳戶。需要 MAILTRAP_ORGANIZATION_ID 環境變數和子帳戶管理權限。

參數：

• name（必要）：新子帳戶的顯示名稱

開發

1. 複製儲存庫：

git clone https://github.com/mailtrap/mailtrap-mcp.git
cd mailtrap-mcp

2. 安裝相依套件：

npm install

使用 Claude Desktop 或 Cursor 進行設定

[!TIP] 請參閱設定章節中的設定檔位置。

加入以下設定：

{
  "mcpServers": {
    "mailtrap": {
      "command": "node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

如果您使用 asdf 管理 Node.js，應使用執行檔的絕對路徑：

（Mac 範例）

{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users/<username>/.asdf/shims/node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "PATH": "/Users/<username>/.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
        "ASDF_DATA_DIR": "/Users/<username>/.asdf",
        "ASDF_NODEJS_VERSION": "20.6.1",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

VS Code

[!TIP] 請參閱設定章節中的設定檔位置。

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "node",
        "args": ["/path/to/mailtrap-mcp/dist/index.js"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "[email protected]",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

測試

針對真實 Mailtrap 執行工具

有兩種方式可以針對真實 Mailtrap 帳戶進行端對端工具測試：MCP Inspector 瀏覽器介面用於互動式探索，或其 CLI 模式用於從命令列進行一次性呼叫。

兩者都需要先建置套件：

npm run build

並在您的命令列環境中匯出 MAILTRAP_API_TOKEN 和 MAILTRAP_ACCOUNT_ID（mcp:cli 腳本會將兩者轉發至啟動的伺服器）。

瀏覽器介面

npm run dev

Inspector 會輸出類似 http://localhost:6274 的網址。開啟後，切換到工具分頁，選擇一個工具（例如 get-template），以 JSON 格式填寫參數，然後點擊執行。Mailtrap 的回應會顯示在下方面板中。

CLI

若要在不使用介面的情況下進行一次性呼叫，請使用 npm run mcp:cli。在 -- 之後傳遞 Inspector 的 CLI 旗標，讓 npm 原封不動地轉發：

# List all tools
npm run mcp:cli -- --method tools/list

# Call a tool — flags after the `--`
npm run mcp:cli -- \
  --method tools/call \
  --tool-name get-template \
  --tool-arg template_id=12345

# Multiple --tool-arg flags for tools with several params
npm run mcp:cli -- \
  --method tools/call \
  --tool-name send-sending-domain-setup-instructions \
  --tool-arg sending_domain_id=3938 \
  --tool-arg [email protected]

執行 MCPB 伺服器

# Run the MCPB server directly
node dist/mcpb-server.js

# Or use the provided binary
mailtrap-mcpb-server

[!TIP] 使用 MCP Inspector 進行開發：

npm run dev:mcpb

錯誤處理

此伺服器使用符合 MCP 慣例的結構化錯誤處理：

• VALIDATION_ERROR：輸入驗證失敗
• CONFIGURATION_ERROR：缺少或無效的設定
• EXECUTION_ERROR：執行階段錯誤
• TIMEOUT：操作逾時（預設 30 秒）

錯誤包含可採取行動的訊息，並以結構化形式記錄。

安全性

• 透過 Zod 架構驗證輸入
• 安全處理環境變數
• 操作逾時保護（30 秒）
• 錯誤輸出中的敏感細節經過清理

記錄

結構化 JSON 記錄，層級包括：INFO、WARN、ERROR、DEBUG。

設定 DEBUG=true 以啟用除錯記錄。

# Example: enable debug logging
DEBUG=true node dist/mcpb-server.js

重要：伺服器將記錄寫入 stderr，因此 stdout 保留給 JSON-RPC 框架。這可防止主機因交錯的記錄而遇到 JSON 解析錯誤。

使用 jq 進行記錄分析範例：

# Filter error logs
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "error")'

# Filter debug logs
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "debug")'

疑難排解

常見問題：

1. 缺少 API 權杖：確保已設定 MAILTRAP_API_TOKEN
2. 沙箱無法運作：在工具呼叫中提供 test_inbox_id 或設定 MAILTRAP_TEST_INBOX_ID 環境變數
3. 逾時錯誤：檢查網路連線和 Mailtrap API 狀態
4. 驗證錯誤：確保已提供所有必要欄位

貢獻

歡迎在 GitHub 上提交錯誤回報和拉取請求。此專案旨在成為一個安全、友善的協作空間，貢獻者應遵守行為準則。

授權

此套件依據 MIT 授權條款以開放原始碼形式提供。

行為準則

所有參與 Mailtrap 專案程式碼庫、議題追蹤器、聊天室和郵件列表的人員，都應遵守行為準則。