Mailgun

Mailgun MCP 服务器

概述

一个用于 Mailgun 的模型上下文协议 (MCP) 服务器，为 AI 代理提供实用、面向工作流的界面，用于发送电子邮件、诊断送达能力以及管理账户操作。

[!NOTE] 此 MCP 服务器在您的本地机器上运行，并通过 stdio 进行通信。Mailgun 目前不提供此服务器的托管版本。

功能

• 消息传递 — 发送电子邮件、检索已存储的消息、重新发送消息
• 域名 — 查看域名详情、验证 DNS 配置、管理跟踪设置（点击、打开、退订）
• Webhooks — 列出、创建和更新事件 Webhooks
• 路由 — 查看和更新入站电子邮件路由规则
• 邮件列表 — 创建、查看和更新邮件列表及其成员
• 模板 — 创建、查看和更新带版本控制的电子邮件模板
• 分析 — 查询发送指标、用量指标和日志
• 统计 — 按域名、标签、提供商、设备和地区查看聚合统计数据
• 抑制 — 查看退信、退订、投诉和允许列表条目
• 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 设置为意外的内部或敏感地址。

输入验证

所有工具参数都根据 Mailgun OpenAPI 规范使用 Zod 模式进行验证。但是，验证取决于 OpenAPI 规范的准确性，某些边缘情况参数可能会回退到宽松验证。Mailgun API 会执行自己的服务器端验证，作为额外的保护层。

调试

MCP 服务器通过 stdio 进行通信。请参阅 MCP 调试指南 进行故障排除。

许可证

Apache 2.0 — 详情请参阅 LICENSE。

贡献

我们欢迎贡献！请随时提交 Pull Request 或开启 Issue。