AI导哈

邮件服务管理协议服务器

Mailgun MCP Server 是一个基于 Model Context Protocol (MCP) 的本地服务器，为 AI 代理提供发送邮件、诊断可送达性和管理账户操作的实用工作流接口。

  • by mailgun
  • TypeScript
  • 本地部署
  • 63 星标
  • 更新于
在 GitHub 查看 mailgun/mailgun-mcp-server

使用说明

Mailgun MCP服务器

概述

A. 模型上下文协议 （MCP）服务器 Mailgun 这为AI代理提供了一个实用的、面向工作流的界面，用于发送电子邮件、诊断可送达性和管理帐户操作。

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

能力

  • 消息传递 --发送电子邮件、检索存储的消息、重新发送消息
  • 领域 --查看域详细信息，验证DNS配置，管理跟踪设置（单击、打开、取消订阅）
  • Webhooks --列出、创建和更新事件webhooks
  • 路线 --查看和更新入站电子邮件路由规则
  • 邮件列表 --创建、查看和更新邮件列表及其成员
  • 模板 --使用版本控制创建、查看和更新电子邮件模板
  • 分析 --查询发送指标、使用指标和日志
  • 统计 --按域、标签、提供商、设备和国家查看聚合统计信息
  • 抑制 --查看跳出、取消订阅、投诉和允许的条目
  • 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密钥

安装

服务器发布到npm为 @mailgun/mcp-server 并在stdio上运行。大多数客户可以按需启动它 npx，所以没有什么可以全局安装的。在下面的每个片段中，替换 YOUR-mailgun-api-key 用你的钥匙 Mailgun API安全设置.

[！提示] 如果您的帐户托管在Mailgun的欧盟地区，请添加 "MAILGUN_API_REGION": "eu" 到 env 块（或 -e MAILGUN_API_REGION=eu 在CLI上）。它默认为 us.

Claude 代码

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

然后运行 /mcp 在克劳德代码中确认 邮筒 服务器已连接。

克劳德桌面版

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

  • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
  • 窗户： %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"
      }
    }
  }
}

光标

打开命令面板并选择 光标设置→ MCP → 添加新的全局MCP服务器，然后添加：

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

法典

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

VS代码（GitHub副本）

将以下内容添加到您的 settings.json:

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

帆板运动

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

双子星命令行工具

添加到 ~/.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 无 （全部） 要启用逗号分隔的产品标签。相当于 --tagsCLI标志优先。

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标志 --通行证 --tags 在MCP客户端配置中 args:

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

通过环境变量 --set 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: 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检查器）指向 dist/mailgun-mcp.js更改后，重新启动MCP客户端会话以加载新版本。

MCP检验员测试

这 MCP检查员 让您在没有完整客户端的情况下练习工具。先构建，然后在构建的服务器上启动它：

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

打开检查器UI，单击 连接，然后使用 列出工具 验证服务器是否正常工作。要测试经过筛选的工具集，请在服务器路径后附加标志：

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

预提交挂钩

npm install 安装一个git预提交钩子（通过husky），运行 oxlint --fix 和 oxfmt 在分阶段的TypeScript/JavaScript文件上运行 npm run check:versions可修复的问题会自动修复并重新上演；引入不可修复的lint错误或版本同步不匹配的提交将被拒绝。如果在此更改之前您已经有了本地克隆，请运行 npm install 一次安装钩子。

关于添加的说明 端点

添加新端点时，如果您使用纯字符串作为其定义，它将默认标记为 send 产品类型 _meta 现场。如果您想将其标记为其他产品，请使用的对象版本 EndpointEntry 类型。

安全考虑

API密钥隔离

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

本地执行

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

API密钥权限

使用专门的Mailgun API密钥，其权限范围仅限于您需要的操作。服务器公开读取和更新操作，但不公开任何删除操作，这限制了意外操作的爆炸半径。

速率限制

服务器未实现客户端速率限制。来自AI的每个工具调用都直接转换为Mailgun API请求。服务器依赖Mailgun的服务器端速率限制来防止滥用——超过这些限制的请求将向AI助手返回错误。

快速注射

与任何MCP服务器一样，精心设计的或对抗性的提示可能会诱使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——请参阅 许可证 了解详情。

贡献

我们欢迎捐款！请随时提交 拉取请求 或打开 问题.

相关 MCP