Mailgun

Mailgun MCP 伺服器

概觀

一個適用於 Mailgun 的 Model Context Protocol (MCP) 伺服器，為 AI 代理提供實用、以工作流程為導向的介面，用於發送電子郵件、診斷送達率及管理帳戶操作。

[!NOTE] 此 MCP 伺服器在您的本機上執行，並透過 stdio 進行通訊。Mailgun 目前不提供此伺服器的託管版本。

功能

• 訊息傳遞 — 發送電子郵件、擷取已儲存的訊息、重新發送訊息
• 網域 — 檢視網域詳細資料、驗證 DNS 設定、管理追蹤設定（點擊、開啟、取消訂閱）
• Webhook — 列出、建立及更新事件 Webhook
• 路由 — 檢視及更新傳入電子郵件路由規則
• 郵件列表 — 建立、檢視及更新郵件列表及其成員
• 範本 — 建立、檢視及更新具備版本控制的電子郵件範本
• 分析 — 查詢發送指標、用量指標及記錄
• 統計資料 — 依網域、標籤、提供者、裝置及國家/地區檢視彙總統計資料
• 封鎖名單 — 檢視退信、取消訂閱、投訴及允許清單項目
• IP 與 IP 集區 — 檢視 IP 指派及專用 IP 集區設定
• 退信分類 — 分析退信類型及傳遞問題
• 驗證 — 在發送前驗證電子郵件地址的送達率及語法 (validate)
• 最佳化（收件匣放置） — 擷取收件匣放置 / 種子測試結果以評估送達率 (optimize)
• 檢查（電子郵件預覽） — 擷取跨用戶端的電子郵件呈現及預覽測試結果 (inspect)
• 帳戶限制 — 檢視自訂的每月發送限制

上述括號中的標籤 (validate、optimize、inspect) 是 標籤篩選 所使用的產品標籤。其他所有功能均註冊在 send 標籤下。

[!NOTE] 工具僅限於讀取和更新操作 — 不公開任何刪除操作，這可將意外動作的影響範圍降至最低。請參閱安全性考量。

運作方式

此伺服器由 OpenAPI 驅動。啟動時，它會解析捆綁的 Mailgun OpenAPI 規格，並將一組經過策劃的端點允許清單註冊為 MCP 工具，從規格中產生每個工具的輸入結構描述（透過 Zod）。每個工具都會標註一個 Mailgun 產品標籤 (send、validate、optimize 或 inspect)。所有相符的工具都會預先註冊 — 沒有延遲或隨需載入。標籤篩選 會在啟動時套用，以界定哪些工具會被註冊，因此給定的工作流程可以只公開其所需的產品。

先決條件

• Node.js（v20.12 或更高版本）
• Mailgun 帳戶和 API 金鑰

安裝

此伺服器以 @mailgun/mcp-server 的名稱發佈到 npm，並透過 stdio 執行。大多數用戶端可以使用 npx 隨需啟動它，因此無需全域安裝。在下面的每個程式碼片段中，請將 YOUR-mailgun-api-key 替換為來自您 Mailgun API 安全設定 的金鑰。

[!TIP] 如果您的帳戶託管在 Mailgun 的歐盟區域，請在 env 區塊（或在 CLI 上使用 -e MAILGUN_API_REGION=eu）中新增 "MAILGUN_API_REGION": "eu"。其預設值為 us。

Claude Code

claude mcp add mailgun -e MAILGUN_API_KEY=YOUR-mailgun-api-key -- npx -y @mailgun/mcp-server

然後在 Claude Code 中執行 /mcp 以確認 mailgun 伺服器已連線。

Claude Desktop

開啟 設定 → 開發人員 → 編輯設定，或直接編輯檔案：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mailgun": {
      "command": "npx",
      "args": ["-y", "@mailgun/mcp-server"],
      "env": {
        "MAILGUN_API_KEY": "YOUR-mailgun-api-key",
        "MAILGUN_API_REGION": "us"
      }
    }
  }
}

Cursor

開啟命令面板並選擇 Cursor 設定 → MCP → 新增全域 MCP 伺服器，然後新增：

{
  "mcpServers": {
    "mailgun": {
      "command": "npx",
      "args": ["-y", "@mailgun/mcp-server"],
      "env": {
        "MAILGUN_API_KEY": "YOUR-mailgun-api-key"
      }
    }
  }
}

Codex

codex mcp add mailgun \
  --env MAILGUN_API_KEY=YOUR-mailgun-api-key \
  -- npx -y @mailgun/mcp-server

VS Code (GitHub Copilot)

將以下內容新增至您的 settings.json：

{
  "mcp": {
    "servers": {
      "mailgun": {
        "command": "npx",
        "args": ["-y", "@mailgun/mcp-server"],
        "env": {
          "MAILGUN_API_KEY": "YOUR-mailgun-api-key"
        }
      }
    }
  }
}

Windsurf

{
  "mcpServers": {
    "mailgun": {
      "command": "npx",
      "args": ["-y", "@mailgun/mcp-server"],
      "env": {
        "MAILGUN_API_KEY": "YOUR-mailgun-api-key"
      }
    }
  }
}

Gemini CLI

新增至 ~/.gemini/settings.json：

{
  "mcpServers": {
    "mailgun": {
      "command": "npx",
      "args": ["-y", "@mailgun/mcp-server"],
      "env": {
        "MAILGUN_API_KEY": "YOUR-mailgun-api-key"
      }
    }
  }
}

設定

環境變數

變數	必要	預設值	說明
MAILGUN_API_KEY	是	—	您的 Mailgun API 金鑰
MAILGUN_API_REGION	否	us	API 區域：us 或 eu
MAILGUN_API_HOSTNAME	否	（從區域衍生）	覆寫 API 主機名稱（例如 api.eu.mailgun.net）。優先於區域設定。
MAILGUN_MCP_TAGS	否	（全部）	要啟用的產品標籤，以逗號分隔。等同於 --tags。CLI 旗標優先。

CLI 選項

在您用戶端的 args 中，於套件名稱之後傳遞旗標（例如 ["-y", "@mailgun/mcp-server", "--tags", "validate,inspect"]）。

旗標	說明
--tags <list>	要啟用的產品標籤，以逗號分隔（預設：全部）。有效值：send、validate、optimize、inspect。
--list-tags	列印有效的標籤值並結束。
--help、-h	顯示用法並結束。

標籤篩選

您可以將伺服器註冊的工具範圍限定在一個或多個 Mailgun 產品標籤。這對於縮小顯示給模型的工具集非常有用 — 例如，僅向不需要發送功能的工作流程公開驗證工具。

有效標籤：send、validate、optimize、inspect。未指定時，會註冊所有工具（目前的預設值）。

篩選使用 OR 語意：如果工具的任何標籤出現在作用中的集合內，則該工具就會被註冊。

透過 CLI 旗標 — 在您的 MCP 用戶端設定的 args 中傳遞 --tags：

{
  "mcpServers": {
    "mailgun": {
      "command": "npx",
      "args": ["-y", "@mailgun/mcp-server", "--tags", "validate,inspect"],
      "env": {
        "MAILGUN_API_KEY": "YOUR-mailgun-api-key"
      }
    }
  }
}

透過環境變數 — 設定 MAILGUN_MCP_TAGS（如果兩者都存在，CLI 旗標優先）：

"env": {
  "MAILGUN_API_KEY": "YOUR-mailgun-api-key",
  "MAILGUN_MCP_TAGS": "validate,inspect"
}

[!TIP] 使用 --list-tags 執行二進位檔以列印支援的標籤值，或使用 --help 取得完整用法。未知的標籤會在啟動時被拒絕，並顯示明確的錯誤訊息。

提示範例

發送電子郵件

Can you send an email to EMAIL_HERE with a funny email body that makes it sound
like it's from the IT Desk from Office Space? Please use the sending domain
DOMAIN_HERE, and make the email from "postmaster@DOMAIN_HERE"!

[!NOTE] 某些 MCP 用戶端需要付費方案才能叫用發送資料的工具。如果發送失敗且無提示，請檢查您用戶端的方案。

擷取並視覺化發送統計資料

Would you be able to make a chart with email delivery statistics for the past week?

管理範本

Create a welcome email template for new signups on my domain DOMAIN_HERE.
Include a personalized greeting and a call-to-action button.

調查送達率

Can you check the bounce classification stats for my account and tell me
what the most common bounce reasons are?

疑難排解 DNS

Check the DNS verification status for my domain DOMAIN_HERE and tell me
if anything needs fixing.

檢閱封鎖名單

Are there any unsubscribes or complaints for DOMAIN_HERE? Summarize the
top offenders.

管理路由規則

List all my inbound routes and explain what each one does.

建立郵件列表

Create a mailing list called announcements@DOMAIN_HERE and add these
members: alice@example.com, bob@example.com.

比較網域

Compare my sending volume and delivery rates across all my domains for
the past month.

各地區參與度

Break down my email engagement by country and device for DOMAIN_HERE.

檢閱追蹤設定

List all my domains and show which ones have tracking enabled for clicks
and opens.

驗證電子郵件地址

Validate the email address EMAIL_HERE and tell me whether it's safe to send to.

檢查收件匣放置（最佳化）

Pull the inbox placement results for seed test RESULT_ID_HERE and summarize
where my message landed (inbox, spam, or missing) by provider.

預覽電子郵件（檢查）

Get the email preview results for test TEST_ID_HERE and tell me if the email
renders correctly across clients.

開發

從原始碼執行

此伺服器以 TypeScript 編寫。複製、安裝、建置及測試：

git clone https://github.com/mailgun/mailgun-mcp-server.git
cd mailgun-mcp-server
npm install
npm run build
npm test

npm run build 會將 src/ 編譯為 dist/，並複製捆綁的 OpenAPI 規格。請將您的 MCP 用戶端指向建置後的進入點，而非 npx（使用絕對路徑）：

{
  "mcpServers": {
    "mailgun": {
      "command": "node",
      "args": ["/absolute/path/to/mailgun-mcp-server/dist/mailgun-mcp.js"],
      "env": {
        "MAILGUN_API_KEY": "YOUR-mailgun-api-key"
      }
    }
  }
}

編輯時進行即時測試

MCP 伺服器是長時間執行的 stdio 程序，不會熱重載，因此流程為：儲存時重新建置，然後重新連線用戶端以套用變更。

1. 執行一次 npm run build，以便 dist/openapi.yaml 就位。

2. 保持 TypeScript 編譯器執行，以便在每次儲存時重新建置 dist/：

   npx tsc --watch
   

3. 將另一個 MCP 用戶端（或下方的 MCP Inspector）指向 dist/mailgun-mcp.js。變更後，重新啟動 MCP 用戶端工作階段以載入新的建置。

使用 MCP Inspector 進行測試

MCP Inspector 可讓您在沒有完整用戶端的情況下操作工具。請先建置，然後針對建置後的伺服器啟動它：

npm run build
MAILGUN_API_KEY=YOUR-mailgun-api-key npx @modelcontextprotocol/inspector node dist/mailgun-mcp.js

開啟 Inspector UI，點擊 連線，然後使用 列出工具 來驗證伺服器是否正常運作。若要測試篩選後的工具集，請在伺服器路徑後附加旗標：

MAILGUN_API_KEY=YOUR-mailgun-api-key npx @modelcontextprotocol/inspector node dist/mailgun-mcp.js --tags validate,inspect

預先提交掛鉤

npm install 會安裝一個 git 預先提交掛鉤（透過 husky），該掛鉤會對已暫存的 TypeScript/JavaScript 檔案執行 oxlint --fix 和 oxfmt，並執行 npm run check:versions。可修復的問題會自動修復並重新暫存；引入無法修復的 lint 錯誤或版本同步不符的提交將被拒絕。如果您在此變更之前已有本機複製，請執行一次 npm install 以安裝該掛鉤。

關於新增端點的注意事項

新增端點時，如果您對其定義使用純文字字串，它將預設在 _meta 欄位中被標記為 send 產品類型。如果您想將其標記為其他產品，請使用 EndpointEntry 類型的物件版本。

安全性考量

API 金鑰隔離

您的 Mailgun API 金鑰會作為環境變數傳遞，絕不會公開給 AI 模型本身 — 它僅由 MCP 伺服器程序用於驗證請求。伺服器不會記錄 API 金鑰、請求參數或回應資料。

本機執行

伺服器在您的本機上執行。所有與 Mailgun API 的通訊均透過 HTTPS 進行，並強制執行 TLS 憑證驗證。除了 Mailgun API 之外，不會將任何資料傳送給第三方服務。

API 金鑰權限

使用專用的 Mailgun API 金鑰，並將其權限範圍限定在僅限您需要的操作。伺服器公開讀取和更新操作，但不公開任何刪除操作，這限制了意外動作的影響範圍。

速率限制

伺服器不會實作用戶端速率限制。來自 AI 的每個工具呼叫都會直接轉換為一個 Mailgun API 請求。伺服器依賴 Mailgun 的伺服器端速率限制來防止濫用 — 超過這些限制的請求將向 AI 助理傳回錯誤。

提示注入

與任何 MCP 伺服器一樣，特製或對抗性的提示可能會誘使 AI 助理呼叫您未預期的操作 — 例如，修改追蹤設定或讀取郵件列表成員。在核准動作之前，請檢閱 AI 助理的工具呼叫確認，尤其是在不受信任的提示內容中。

Webhook URL

Webhook 建立和更新操作接受透過 AI 助理提供的任意 URL。MCP 伺服器會將這些 URL 傳遞給 Mailgun API，而不進行額外驗證。Mailgun 負責驗證 Webhook 目的地。確保您的 AI 助理不會將 Webhook URL 設定為非預期的內部或敏感位址。

輸入驗證

所有工具參數都會使用 Zod 結構描述，根據 Mailgun OpenAPI 規格進行驗證。然而，驗證取決於 OpenAPI 規格的正確性，某些邊緣情況的參數可能會回退到寬鬆的驗證。Mailgun API 會執行其自身的伺服器端驗證，作為額外的保護層。

除錯

MCP 伺服器透過 stdio 進行通訊。如需疑難排解，請參閱 MCP 除錯指南。

授權

Apache 2.0 — 詳情請參閱 LICENSE。

貢獻

我們歡迎貢獻！請隨時提交 Pull Request 或開啟 Issue。