Mailgun MCP Server

Mailgun MCP 服务

概述

这是一个适用于 Mailgun 的 Model Context Protocol（MCP）服务，为 AI Agent 提供实用且面向工作流的接口，用于发送电子邮件、诊断送达情况和管理账户操作。

说明

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

功能

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

上面的括号标签（validate、optimize、inspect）是 标签筛选 使用的产品标签。其他所有功能均注册在 send 标签下。

说明

工具仅支持读取和更新操作 — 不提供删除操作，从而降低意外操作的影响范围。请参阅安全注意事项。

工作原理

此服务由 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 安全设置获取的密钥。

提示

如果你的账户托管在 Mailgun 的 EU 区域，请在 env 块中添加 "MAILGUN_API_REGION": "eu"（或在命令行中添加 -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

打开 设置 → 开发者 → 编辑配置，或直接编辑文件：

• 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	否	（全部）	要启用的产品标签，以逗号分隔。等同于 --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"
}

提示

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

说明

某些 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.

验证电子邮件地址

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

检查收件箱投递位置（Optimize）

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

预览电子邮件（Inspect）

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 可让你在不使用完整客户端的情况下调用工具。先构建，再针对构建后的服务启动 Inspector：

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

打开 Inspector UI，点击 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 来安装此钩子。

关于添加 端点 的说明

添加新端点时，如果使用普通字符串作为定义，它默认会在 _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，不会进行额外验证。Webhook 目标的验证由 Mailgun 负责。请确保 AI 助手不会将 Webhook URL 设置为非预期的内部地址或敏感地址。

输入验证

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

调试

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

许可证

Apache 2.0 — 详情请参阅 LICENSE。

贡献

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