Mailgun MCP Server

官方

与Mailgun API进行交互。

GitHub

文档

Mailgun MCP 服务器

概述

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

注意： 此 MCP 服务器在您的本地机器上运行。Mailgun 目前不提供此服务器的托管版本。

功能

消息 — 发送邮件、检索已存储的消息、重新发送消息
域名 — 查看域名详情、验证 DNS 配置、管理跟踪设置（点击、打开、退订）
Webhooks — 列出、创建、更新和删除事件 Webhooks
路由 — 查看和更新入站邮件路由规则
邮件列表 — 创建和管理邮件列表及其成员
模板 — 创建和管理带版本控制的邮件模板
分析 — 查询发送指标、用量指标和日志
统计 — 按域名、标签、提供商、设备和地区查看聚合统计数据
抑制 — 查看退信、退订、投诉和允许列表条目
IP 和 IP 池 — 查看 IP 分配和专用 IP 池配置
退信分类 — 分析退信类型和送达问题

先决条件

Node.js（v20.12 或更高版本）
Mailgun 账户和 API 密钥

快速开始

配置

将以下内容添加到您的 MCP 客户端配置中：

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

环境变量

变量	必需	默认值	描述
`MAILGUN_API_KEY`	是	—	您的 Mailgun API 密钥
`MAILGUN_API_REGION`	否	`us`	API 区域：`us` 或 `eu`
`MAILGUN_MCP_TAGS`	否	(全部)	要启用的产品标签，以逗号分隔。等同于 `--tags`。CLI 标志优先。

标签过滤

您可以将服务器注册的工具范围限定为一个或多个 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"
}

可发现性 — 使用 --list-tags 运行二进制文件以打印支持的标签值，或使用 --help 获取完整用法。未知标签会在启动时被拒绝，并显示明确的错误消息。

客户端特定的配置路径

Claude Desktop (macOS)：~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows)：%APPDATA%/Claude/claude_desktop_config.json
Claude Code：运行 claude mcp add 或编辑 ~/.claude.json

示例提示

发送邮件

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"!

注意：某些 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: [email protected], [email protected].

比较域名

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.

开发

要从源代码运行，请克隆仓库并直接使用 node：

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

在您的 MCP 客户端配置中，将 npx 命令替换为：

"command": "node",
"args": ["/path/to/mailgun-mcp-server/src/mailgun-mcp.js"]

预提交钩子

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。