Mailgun

Mailgun MCP Server

概述

一个适用于 Mailgun 的 Model Context Protocol (MCP) 服务器，为 AI 代理提供实用、面向工作流的接口，用于发送电子邮件、诊断送达能力以及管理账户操作。

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

功能

• 消息 — 发送电子邮件、检索已存储的消息、重新发送消息
• 域名 — 查看域名详情、验证 DNS 配置、管理跟踪设置（点击、打开、取消订阅）
• Webhook — 列出、创建和更新事件 webhook
• 路由 — 查看和更新入站电子邮件路由规则
• 邮件列表 — 创建、查看和更新邮件列表及其成员
• 模板 — 创建、查看和更新带版本控制的电子邮件模板
• 分析 — 查询发送指标、使用情况指标和日志
• 统计 — 按域名、标签、提供商、设备和国家/地区查看汇总统计数据
• 抑制列表 — 查看退信、取消订阅、投诉和允许列表条目
• IP 和 IP 池 — 查看 IP 分配和专用 IP 池配置
• 退信分类 — 分析退信类型和投递问题
• 验证 — 发送前验证电子邮件地址的送达能力和语法 (validate)
• Optimize（收件箱投放） — 获取收件箱投放 / 种子测试结果，以评估送达能力 (optimize)
• Inspect（电子邮件预览） — 获取不同客户端中的电子邮件渲染和预览测试结果 (inspect)
• 账户限额 — 查看自定义月度发送限额

上述标签 (validate, optimize, inspect) 是 标签筛选 使用的产品标签。其他所有功能均注册在 send 标签下，并划分为 send.<group> 个工具集。

[!NOTE] 工具仅限读取和更新操作 — 不提供删除操作，因此可将意外操作的影响范围控制在较小范围内。请参阅安全注意事项。

工作原理

此服务器由 OpenAPI 驱动。启动时，它会解析内置的 Mailgun OpenAPI 规范，并将精选的端点允许列表注册为 MCP 工具，再根据该规范使用 Zod 生成每个工具的输入架构。每个工具都会标注 Mailgun 产品标签 (send, validate, optimize 或 inspect)、所属工具集，以及是否为只读工具。

默认情况下，服务器会在启动时加载所有工具。使用 --tags dynamic 时，它会加载一组较小的核心工具，以及模型按需加载更多工具集时使用的三个工具，从而减少发送给模型的工具定义。标签筛选则会在启动时加载一组固定工具，因此可以针对特定工作流，仅开放所需的产品功能。

先决条件

• Node.js (v20.12 或更高版本)
• Mailgun 账户和 API 密钥

安装

此服务器以 @mailgun/mcp-server 的形式发布到 npm，并通过 stdio 运行。大多数客户端都可以使用 npx 按需启动它，因此无需全局安装。在下面的每个代码片段中，将 YOUR-mailgun-api-key 替换为你在 Mailgun API 安全设置中获取的密钥。

[!TIP] 如果你的账户托管在 Mailgun 的欧盟区域，请将 "MAILGUN_API_REGION": "eu" 添加到 env 块中（或在 CLI 中使用 -e 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

打开 Settings → Developer → Edit Config，或直接编辑文件：

• 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 Settings → MCP → Add new global MCP server，然后添加：

{
  "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	否	（全部）	要加载的逗号分隔标签或工具集；或者使用 dynamic 加载核心工具，并按需加载更多工具。等同于 --tags。CLI 标志优先。

CLI 选项

在客户端的 args 中，包名称后传入标志（例如 ["-y", "@mailgun/mcp-server", "--tags", "validate,inspect"]）。

标志	说明
--tags <list>	要加载的逗号分隔标签或工具集（默认：全部）。有效值：all、dynamic、core、send、validate、optimize、inspect，以及 send.<group> 工具集。
--list-tags	打印所有有效的 --tags 值及其说明，然后退出。
--help、-h	显示用法并退出。

按需加载工具集

使用 --tags dynamic（或 MAILGUN_MCP_TAGS=dynamic）时，服务器会以以下核心工具启动：

工具	用途
post-v3-domain-messages	发送电子邮件
get-v4-domains	列出域名
get-v4-domains-name	域名详情和 DNS 记录
put-v4-domains-name-verify	重新检查域名的 DNS 记录
get-v3-domains-name-tracking	跟踪设置
get_metrics_summary	关键发送指标摘要
post-v1-analytics-metrics	查询账户指标
post-v1-analytics-logs	查询事件日志
post-v2-bounce-classification-metrics	退信分类指标
get-v3-domain-bounces	列出退信
get-v3-domain-bounces-address	查找退信记录
get-v3-domain-unsubscribes	列出取消订阅记录
get-v3-domain-complaints	列出投诉
get-v3-domain-templates	列出模板
validate_email	验证电子邮件地址

每个工具都属于一个工具集。任务需要时，模型会加载该工具集中的其余工具：

工具集	工具数	内容
send.messages	3	发送电子邮件；检索和重新发送已存储的消息
send.domains	8	域名、DNS 验证、发送队列、跟踪设置
send.webhooks	4	域名 webhook
send.account	8	账户 IP、专用 IP 池、自定义发送限额
send.message_tags	8	消息标签、按标签统计、标签限额
send.analytics	12	统计和汇总、分析指标和日志、退信分类
send.suppressions	8	退信、取消订阅、投诉、允许列表
send.routes	3	入站路由
send.lists	8	邮件列表和成员
send.templates	8	模板和模板版本
validate	1	电子邮件地址验证
optimize	1	收件箱投放测试结果
inspect	1	电子邮件预览测试结果

模型通过三个额外工具加载工具集：

• mailgun_list_toolsets 列出所有工具集及其工具，并标明哪些已加载、哪些会更改数据。提供工具名称时，它会改为返回该工具的输入架构。
• mailgun_enable_toolset 加载一个或多个工具集。随后，服务器会通知客户端工具列表已更改 (notifications/tools/list_changed)，新工具会与核心工具一同显示。响应会列出新工具，但不包含其输入架构；输入架构会随更新后的工具列表一同提供。
• mailgun_call_tool 按名称运行只读工具，无论其所属工具集是否已加载。对于工具列表不会在发生更改后刷新的客户端，这是一个备用方案。它不会运行核心工具或会更改数据的工具，因此这些工具始终作为独立工具调用运行。

已加载的工具集会一直保留，直到客户端断开连接。按需加载需要客户端在服务器报告更改时刷新工具列表；Claude Code 支持此功能。在不支持此功能的客户端中，新加载的工具不会显示：只读工具仍可通过 mailgun_call_tool 使用，而会更改数据的工具则需要使用默认设置（所有工具）或 --tags，例如 --tags core,send.templates。

标签筛选

将 --tags 或 MAILGUN_MCP_TAGS 设置为除 dynamic 以外的任何值，都会在启动时仅加载匹配的工具，而不加载用于加载工具的工具。可用它来缩小模型可见的工具范围（例如，对于不发送电子邮件的工作流，仅加载验证工具）。

有效值（运行 --list-tags 查看说明）：

• all — 所有工具（默认）
• dynamic — 核心工具，并按需加载其他工具集。请单独使用；与其他值组合会导致启动失败。
• core — 仅加载上文列出的核心工具
• send、validate、optimize、inspect — 加载该产品的所有工具（send 涵盖所有 send.<group> 工具集）
• 工具集 ID，例如 send.templates

筛选采用 OR 语义：只要工具匹配列表中的任意一个值，就会加载。例如，core,send.templates 会加载核心工具以及所有模板工具。

通过 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 界面，点击 Connect，然后使用 List Tools 验证服务器是否正常工作。若要测试经过筛选的工具集，请在服务器路径后追加标志：

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 来安装钩子。

关于添加端点的说明

端点按工具集分组在 endpointGroups 中。普通字符串条目会从其工具集获取产品标签（send.templates → send），且只有当它是 GET 时才会被视为只读。使用 EndpointEntry 的对象形式来设置工具名称、将工具标记为 core（在动态模式下于启动时加载），或将仅查询数据的 POST 标记为 readOnly: true。

安全注意事项

API 密钥隔离

你的 Mailgun API 密钥通过环境变量传递，不会暴露给 AI 模型本身——它仅由 MCP 服务器进程用于验证请求。服务器不会记录 API 密钥、请求参数或响应数据。

本地执行

服务器在你的计算机上本地运行。与 Mailgun API 的所有通信都通过 HTTPS 进行，并强制执行 TLS 证书验证。除 Mailgun API 外，不会向第三方服务发送任何数据。

API 密钥权限

请使用专用的 Mailgun API 密钥，并将权限范围限制为你需要的操作。服务器提供读取和更新操作，但不提供任何删除操作，从而限制意外操作造成的影响范围。

速率限制

服务器不实施客户端速率限制。AI 发起的每次工具调用都会直接转换为 Mailgun API 请求。服务器依赖 Mailgun 的服务端速率限制来防止滥用——超出限制的请求会向 AI 助手返回错误。

提示注入

与任何 MCP 服务器一样，精心构造或带有对抗性的提示可能会诱使 AI 助手调用你无意执行的操作，例如修改跟踪设置或读取邮件列表成员。在批准操作前，请查看 AI 助手的工具调用确认，尤其是在提示来源不可信的情况下。

工具加载与审批

每个工具都带有 MCP readOnlyHint 注解，因此客户端可以区分只读取数据的工具和会更改数据的工具（例如，在请求审批时）。mailgun_list_toolsets 和 mailgun_call_tool 是只读的。mailgun_enable_toolset 会更改会话可见的工具，因此不会被标记为只读，但它不会更改 Mailgun 中的任何内容。mailgun_call_tool 只运行不属于核心集合的只读工具，因此批准它绝不会发送电子邮件或更改账户设置。会更改数据的工具始终作为独立的工具调用运行。

按需加载工具集可以减少模型可见的内容；但这并非访问控制，因为模型可以加载任何工具集。若要限制服务器实际公开的工具，请使用 --tags。

Webhook URL

Webhook 创建和更新操作接受由 AI 助手提供的任意 URL。MCP 服务器会将这些 URL 传递给 Mailgun API，不进行额外验证。Webhook 目标地址由 Mailgun 负责验证。请确保 AI 助手不会将 Webhook URL 设置为非预期的内部地址或敏感地址。

输入验证

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

调试

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

许可证

Apache 2.0 — 详情请参阅 LICENSE。

贡献

欢迎贡献！欢迎提交 Pull Request 或创建 Issue。