Mailtrap MCP Server

MCP Mailtrap 服务器

一个 MCP 服务器，提供通过 Mailtrap 在沙箱中发送和测试邮件的工具。

先决条件

在使用此 MCP 服务器之前，您需要：

1. 创建 Mailtrap 账户
2. 验证您的域名
3. 从 Mailtrap API 设置 获取您的 API 令牌
4. 从 Mailtrap 账户管理 获取您的账户 ID

必需的环境变量：

• MAILTRAP_API_TOKEN - 所有功能必需
• MAILTRAP_ACCOUNT_ID - 模板、统计信息、邮件日志、沙箱列表/显示和发送域名所必需。仅对于 send-email 和 send-sandbox-email 是可选的。

可选（可以改为作为工具参数传递）：

• DEFAULT_FROM_EMAIL - 当未向 send-email 或 send-sandbox-email 提供 from 时的默认发件人邮箱。允许通过 from 参数在每次调用时切换发件人。
• MAILTRAP_TEST_INBOX_ID - 当未提供 test_inbox_id 时，沙箱工具的默认测试收件箱 ID。允许通过 test_inbox_id 参数在每次调用时切换收件箱。
• MAILTRAP_SANDBOX_ID - 当未提供 sandbox_id 时，沙箱工具的默认沙箱 ID。允许通过 sandbox_id 参数在每次调用时切换沙箱。
• MAILTRAP_ORGANIZATION_ID - 组织工具（list-sub-accounts、create-sub-account）所必需。
• MAILTRAP_ORGANIZATION_API_TOKEN - 组织范围的 API 令牌。组织工具所必需（与 MAILTRAP_API_TOKEN 分开）。

快速安装

Smithery CLI

Smithery 是一个适用于所有 AI 客户端的 MCP 服务器注册表安装程序和管理器。

npx @smithery/cli install mailtrap

Smithery 自动处理客户端配置并提供交互式设置过程。这是在本地开始使用 MCP 服务器的最简单方法。

设置

Claude Desktop

使用 MCPB 安装 Mailtrap 服务器。您可以在 Releases 中找到这些文件。
下载 .MCPB 文件并打开它。如果您有 Claude Desktop，它将打开并建议进行配置。

Claude Desktop 或 Cursor

添加以下配置：

{
  "mcpServers": {
    "mailtrap": {
      "command": "npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

如果您使用 asdf 管理 Node.js，则必须使用可执行文件的绝对路径（Mac 示例）

{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users/<username>/.asdf/shims/npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "PATH": "/Users/<username>/.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
        "ASDF_DATA_DIR": "/Users/<username>/.asdf",
        "ASDF_NODEJS_VERSION": "20.6.1",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Claude Desktop 配置文件位置

Mac：~/Library/Application Support/Claude/claude_desktop_config.json

Windows：%APPDATA%\Claude\claude_desktop_config.json

Cursor 配置文件位置

Mac：~/.cursor/mcp.json

Windows：%USERPROFILE%\.cursor\mcp.json

VS Code

手动更改配置

在命令面板中运行：Preferences: Open User Settings (JSON)

然后，在设置文件中，添加以下配置：

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "npx",
        "args": ["-y", "mcp-mailtrap"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "[email protected]",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

[!TIP] 更改“env”部分后，不要忘记重新启动您的 MCP 服务器。

MCP Bundle (MCPB)

为了在支持 MCP Bundles 的主机中轻松安装，您可以分发一个 .mcpb bundle 文件。

# Build TypeScript and pack the MCPB bundle
npm run mcpb:pack

# Inspect bundle metadata
npm run mcpb:info

# Sign the bundle for distribution (optional)
npm run mcpb:sign

这将使用仓库 manifest.json 和 dist/ 中的构建工件创建 mailtrap-mcp.mcpb。

用法

配置完成后，您可以要求代理发送邮件和管理模板，例如：

邮件发送操作：

• “向 [email protected] 发送一封主题为‘明天会议’的邮件，并附上关于我们即将举行的会议的友好提醒。”
• “向 [email protected] 发送关于项目更新的邮件，并抄送团队 [email protected]”
• “使用变量 { name: 'Alex' } 将欢迎模板 (uuid b81aabcd-1a1e-41cf-91b6-eca0254b3d96) 发送给 [email protected]”
• “向 [email protected] 发送一封主题为‘测试模板’的沙箱邮件，以预览我们的欢迎邮件的外观”

邮件日志（调试投递）：

• “列出我最近发送的邮件日志”
• “显示发送给 [email protected] 的邮件日志”
• “获取 ID 为 abc-123-uuid 的邮件日志消息，以检查投递状态”

发送统计信息：

• “获取 2025 年 1 月的发送统计信息”
• “显示上个月按域名细分的投递率”
• “从 2025-01-01 到 2025-01-31，我的邮件统计信息按类别如何？”

沙箱操作：

• “从我的沙箱收件箱获取所有消息”
• “显示沙箱消息的第一页”
• “在我的沙箱收件箱中搜索包含‘test’的消息”
• “显示 ID 为 5159037506 的沙箱消息的详细信息”

模板操作：

• “列出我的 Mailtrap 账户中的所有邮件模板”
• “创建一个名为‘欢迎邮件’的新邮件模板，主题为‘欢迎来到我们的平台！’”
• “更新 ID 为 12345 的模板，将主题更改为‘更新后的欢迎消息’”
• “删除 ID 为 67890 的模板”

发送域名：

• “列出我的发送域名”
• “获取 ID 为 3938 的发送域名”
• “为 example.com 创建一个发送域名”
• “删除发送域名 3938”
• “获取发送域名 3938 及其 DNS 设置说明”

可用工具

send-email

通过 Mailtrap 发送事务性邮件。支持两种互斥模式——内联内容（subject + text/html）或基于模板（template_uuid）。

参数：

• from（可选）：作为邮件字符串或 { email, name? } 的发件人。如果未提供，则使用 DEFAULT_FROM_EMAIL。
• to（可选）：收件人——单个邮件/{ email, name? } 或数组。如果提供了 cc 或 bcc，则为可选；to / cc / bcc 中至少有一个必须包含收件人。
• cc（可选）：抄送收件人数组（每个为邮件字符串或 { email, name? }）。
• bcc（可选）：密送收件人数组（每个为邮件字符串或 { email, name? }）。
• subject（条件性）：邮件主题行。内联发送时必需；设置 template_uuid 时必须省略。
• text（条件性）：邮件正文文本。内联发送时必需（与 html 一起或代替它）；设置 template_uuid 时必须省略。
• html（条件性）：邮件正文的 HTML 版本。内联发送时必需（与 text 一起或代替它）；设置 template_uuid 时必须省略。
• category（可选）：用于跟踪和分析的邮件类别。设置 template_uuid 时必须省略。
• template_uuid（可选）：使用 Mailtrap 邮件模板代替内联内容。设置后，subject / text / html / category 必须省略（根据 Mailtrap API）。
• template_variables（可选）：替换到 template_uuid 引用的模板中的变量对象。仅允许与 template_uuid 一起使用。

batch-send-transactional-email

在一个 Mailtrap API 调用中发送一批事务性邮件（默认发送流）。共享字段放在 base 上；每个收件人的覆盖放在 requests[] 中。每个请求必须通过 to、cc 或 bcc 包含至少一个收件人。与 send-email 相同的内联与模板互斥——在将基础与每个请求合并后检查。

参数：

• base（可选）：包含批次共享字段的对象。
  • from（可选）：作为邮件字符串或 { email, name? } 的发件人。回退到 DEFAULT_FROM_EMAIL。
  • reply_to（可选）：回复地址。
  • subject / text / html / category（可选，内联模式）：每个请求的默认内容。
  • template_uuid / template_variables（可选，模板模式）：默认模板 + 变量。与内联字段互斥。
  • custom_variables（可选）：默认自定义变量（字符串值）。
  • headers（可选）：默认自定义标头。
• requests（必需）：每个收件人消息的非空数组。每个条目包含：
  • to（可选）：收件人——字符串、{ email, name? } 或数组。如果提供了 cc 或 bcc，则为可选；to / cc / bcc 中至少有一个必须包含收件人。
  • cc、bcc、reply_to（可选）。
  • 内联（subject/text/html/category）或模板（template_uuid/template_variables）覆盖；任何省略的字段回退到匹配的 base 值。
  • custom_variables、headers（可选）。

batch-send-bulk-email

通过 Mailtrap 的批量流 API 发送一批批量邮件。与 batch-send-transactional-email 相同的 base + requests[] 形状、验证和内联与模板规则——唯一的区别是此工具通过批量端点而不是事务性端点路由调用。请参阅上面的参数。

list-email-logs

列出已发送的邮件日志（投递历史记录），支持可选的分页和筛选。用于在 IDE 中调试投递问题。

参数：

• search_after（可选）：来自上一个响应的 next_page_cursor 的分页游标
• sent_after（可选）：ISO 8601 日期/时间；仅显示在此时间之后发送的日志
• sent_before（可选）：ISO 8601 日期/时间；仅显示在此时间之前发送的日志
• from_email（可选）：按发件人邮箱筛选；与 from_operator 一起使用（默认：ci_equal）
• to_email（可选）：按收件人邮箱筛选；与 to_operator 一起使用（默认：ci_equal）
• status（可选）：按投递状态筛选：delivered、not_delivered、enqueued、opted_out；与 status_operator 一起使用（默认：equal）
• subject（可选）：按邮件主题筛选；与 subject_operator 一起使用（默认：ci_contain）。使用 subject_operator：empty/not_empty 按主题是否存在筛选。
• sending_domain_id（可选）：按发送域名 ID（数字）筛选；与 sending_domain_id_operator 一起使用（默认：equal）
• sending_stream（可选）：按流筛选：transactional 或 bulk；与 sending_stream_operator 一起使用（默认：equal）
• events（可选）：按事件类型筛选：delivery、open、click、bounce、spam、unsubscribe、soft_bounce、reject、suspension；与 events_operator 一起使用（include_event / not_include_event）
• clicks_count / opens_count（可选）：按点击/打开次数筛选；与 *_operator 一起使用：equal、greater_than、less_than
• client_ip / sending_ip（可选）：按 IP 筛选；与 *_operator 一起使用：equal、not_equal、contain、not_contain
• email_service_provider_response（可选）：按提供商响应文本筛选；与 *_operator 一起使用（ci_contain 等）
• email_service_provider（可选）：按提供商（精确）筛选；与 *_operator 一起使用：equal、not_equal
• recipient_mx（可选）：按收件人 MX 筛选；与 recipient_mx_operator 一起使用（ci_contain 等）
• category（可选）：按邮件类别筛选；与 category_operator 一起使用：equal、not_equal

所有参数均为可选。

get-email-log-message

通过 ID (UUID) 获取单个邮件日志消息：可读摘要（发件人、收件人、主题、发送时间、状态、类别、流、互动、投递上下文），然后是详细的事件历史记录。可选地，使用 include_content: true，当 Mailtrap 公开原始消息 URL 时，您还可以加载并显示消息正文（HTML 和纯文本）。

参数：

• message_id（必需）：邮件日志消息的 UUID（来自发送响应或 list-email-logs）。使用 list-email-logs 查找消息 ID。
• include_content（可选）：当为 true 时，获取原始 EML（如果 raw_message_url 可用）并附加解析后的 HTML 和纯文本正文部分，类似于 show-sandbox-email-message。

get-sending-stats

获取日期范围内的邮件发送统计信息（投递、退回、打开、点击、垃圾邮件率）。可以选择按域名、类别、邮件服务提供商或日期细分。无需离开编辑器即可检查投递率。

参数：

• start_date（必需）：统计信息范围的开始日期 (YYYY-MM-DD)
• end_date（必需）：统计信息范围的结束日期 (YYYY-MM-DD)
• breakdown（可选）：如何细分统计信息：aggregated（默认）、by_domain、by_category、by_email_service_provider 或 by_date
• sending_domain_ids（可选）：将结果限制为这些发送域名 ID（整数数组）
• sending_streams（可选）：限制为 transactional 和/或 bulk（字符串数组）
• categories（可选）：限制为这些邮件类别（字符串数组）
• email_service_providers（可选）：限制为这些提供商，例如 Google、Yahoo、Outlook（字符串数组）

create-template

在您的 Mailtrap 账户中创建一个新的邮件模板。

参数：

• name（必需）：模板名称
• subject（必需）：邮件主题行
• html（或 text 必需）：模板的 HTML 内容
• text（或 html 必需）：模板的纯文本版本
• category（可选）：模板类别（默认为“General”）

list-templates

列出您的 Mailtrap 账户中的所有邮件模板。

参数：

• 无需参数

get-template

通过 ID 获取单个邮件模板，包括主题、类别和 HTML/文本正文。

参数：

• template_id（必需）：要获取的模板的 ID

update-template

更新现有的邮件模板。

参数：

• template_id（必需）：要更新的模板的 ID
• name（可选）：模板的新名称
• subject（可选）：新的邮件主题行
• html（可选）：模板的新 HTML 内容
• text（可选）：模板的新纯文本版本
• category（可选）：模板的新类别

[!NOTE] 调用 update-template 执行更新时，必须提供至少一个可更新字段（名称、主题、html、文本或类别）。

delete-template

删除现有的邮件模板。

参数：

• template_id（必需）：要删除的模板的 ID

send-sandbox-email

向您的 Mailtrap 测试收件箱发送邮件，用于开发和测试目的。这非常适合在不向真实收件人发送邮件的情况下测试邮件模板。支持与 send-email 相同的两种模式——内联内容或基于模板（template_uuid）。

参数：

• test_inbox_id（可选）：Mailtrap 测试收件箱 ID。除非设置了 MAILTRAP_TEST_INBOX_ID，否则为必需；每次调用时传递以定位特定收件箱。
• from（可选）：作为邮件字符串或 { email, name? } 的发件人。如果未提供，则使用 DEFAULT_FROM_EMAIL。
• to（可选）：收件人，作为逗号分隔的字符串，或邮件字符串/{ email, name? } 对象的数组。如果提供了 cc 或 bcc，则为可选；to / cc / bcc 中至少有一个必须包含收件人。
• cc（可选）：抄送收件人数组（每个为邮件字符串或 { email, name? }）。
• bcc（可选）：密送收件人数组（每个为邮件字符串或 { email, name? }）。
• subject（条件性）：邮件主题行。内联发送时必需；设置 template_uuid 时必须省略。
• text（条件性）：邮件正文文本。内联发送时必需（与 html 一起或代替它）；设置 template_uuid 时必须省略。
• html（条件性）：邮件正文的 HTML 版本。内联发送时必需（与 text 一起或代替它）；设置 template_uuid 时必须省略。
• category（可选）：用于跟踪的邮件类别。设置 template_uuid 时必须省略。
• template_uuid（可选）：使用 Mailtrap 邮件模板代替内联内容。设置后，subject / text / html / category 必须省略。
• template_variables（可选）：替换到 template_uuid 引用的模板中的变量对象。仅允许与 template_uuid 一起使用。

[!NOTE] 对于沙箱工具，在工具调用中提供 test_inbox_id 或设置 MAILTRAP_TEST_INBOX_ID 环境变量。您可以通过传递 test_inbox_id 在每次调用时切换收件箱。

get-sandbox-messages

从您的 Mailtrap 测试收件箱检索消息列表。用于在测试期间检查沙箱中收到了哪些邮件。

参数：

• page（可选）：分页页码（最小值：1）
• last_id（可选）：使用最后一条消息 ID 进行分页。返回指定消息 ID 之后的消息（最小值：1）
• search（可选）：用于筛选消息的搜索查询

[!NOTE] 所有参数均为可选。如果未提供任何参数，将返回收件箱中的第一页消息。使用 page 进行传统分页，使用 last_id 进行基于游标的分页，或使用 search 按内容筛选消息。

show-sandbox-email-message

显示来自 Mailtrap 测试收件箱的特定邮件消息的详细信息和内容，包括 HTML 和文本正文内容。

参数：

• message_id（必需）：要检索的沙箱邮件消息的 ID

[!NOTE] 首先使用 get-sandbox-messages 获取消息列表及其 ID，然后使用此工具查看特定消息的完整内容。

get-sandbox-project

通过 ID 获取沙箱项目，包括其收件箱和邮件计数。

参数：

• project_id（必需）：要获取的项目的 ID

update-sandbox-project

重命名现有的沙箱项目。

参数：

• project_id（必需）：要更新的项目的 ID
• name（必需）：项目的新名称（2–100 个字符）

list-sandboxes

列出 API 令牌可访问的所有项目中的每个沙箱。

参数：

• 无需参数

mark-sandbox-as-read

将沙箱中的所有消息标记为已读。

参数：

• sandbox_id（必需）：要操作的沙箱的 ID

reset-sandbox-credentials

重置沙箱的 SMTP 凭据。返回新的用户名/密码。

参数：

• sandbox_id（必需）：要操作的沙箱的 ID

enable-sandbox-email-address

为沙箱启用通过邮件接收的地址（打开 Mailtrap 地址，该地址通过 SMTP 将消息投递到沙箱）。

参数：

• sandbox_id（必需）：要操作的沙箱的 ID

reset-sandbox-email-address

为沙箱生成一个新的通过邮件接收的地址。

参数：

• sandbox_id（必需）：要操作的沙箱的 ID

forward-sandbox-message

将沙箱消息转发到外部邮件地址。计入您的每月转发配额。

参数：

• sandbox_id（可选）：沙箱 ID。回退到 MAILTRAP_SANDBOX_ID。
• message_id（必需）：要转发的沙箱消息的 ID
• email（必需）：要将消息转发到的邮件地址

update-sandbox-message

将沙箱消息标记为已读或未读。

参数：

• sandbox_id（可选）：沙箱 ID。回退到 MAILTRAP_SANDBOX_ID。
• message_id（必需）：要更新的沙箱消息的 ID
• is_read（必需）：true 标记为已读，false 标记为未读

delete-sandbox-message

删除单个沙箱消息。

参数：

• sandbox_id（可选）：沙箱 ID。回退到 MAILTRAP_SANDBOX_ID。
• message_id（必需）：要删除的沙箱消息的 ID

get-sandbox-message-spam-score

获取沙箱消息的 SpamAssassin 垃圾邮件报告（分数、规则、完整报告）。show-sandbox-email-message 上 include_spam_report: true 的独立替代方案。

参数：

• sandbox_id（可选）：沙箱 ID。回退到 MAILTRAP_SANDBOX_ID。
• message_id（必需）：沙箱消息的 ID

get-sandbox-message-html-analysis

获取沙箱消息的 HTML 分析报告（客户端兼容性分数、有问题的元素）。show-sandbox-email-message 上 include_html_analysis: true 的独立替代方案。

参数：

• sandbox_id（可选）：沙箱 ID。回退到 MAILTRAP_SANDBOX_ID。
• message_id（必需）：沙箱消息的 ID

get-sandbox-message-headers

获取沙箱消息的解析邮件标头。

参数：

• sandbox_id（可选）：沙箱 ID。回退到 MAILTRAP_SANDBOX_ID。
• message_id（必需）：沙箱消息的 ID

get-sandbox-message-html

获取沙箱消息的渲染 HTML 正文。

参数：

• sandbox_id（可选）：沙箱 ID。回退到 MAILTRAP_SANDBOX_ID。
• message_id（必需）：沙箱消息的 ID

get-sandbox-message-text

获取沙箱消息的纯文本正文。

参数：

• sandbox_id（可选）：沙箱 ID。回退到 MAILTRAP_SANDBOX_ID。
• message_id（必需）：沙箱消息的 ID

get-sandbox-message-raw

获取沙箱消息的原始 MIME 格式消息（标头 + 正文）。

参数：

• sandbox_id（可选）：沙箱 ID。回退到 MAILTRAP_SANDBOX_ID。
• message_id（必需）：沙箱消息的 ID

get-sandbox-message-eml

获取呈现为 EML 文件有效负载的消息（适合附加到工单或导入到另一个邮件客户端）。

参数：

• sandbox_id（可选）：沙箱 ID。回退到 MAILTRAP_SANDBOX_ID。
• message_id（必需）：沙箱消息的 ID

get-sandbox-message-html-source

获取沙箱消息的未渲染 HTML 源代码（在任何 Mailtrap 端转换（如 CID 链接重写）之前的 HTML）。

参数：

• sandbox_id（可选）：沙箱 ID。回退到 MAILTRAP_SANDBOX_ID。
• message_id（必需）：沙箱消息的 ID

list-sandbox-attachments

列出沙箱消息上的所有附件（文件名、内容类型、大小、下载路径）。

参数：

• sandbox_id（可选）：沙箱 ID。回退到 MAILTRAP_SANDBOX_ID。
• message_id（必需）：沙箱消息的 ID

get-sandbox-attachment

获取单个附件的元数据和下载 URL。

参数：

• sandbox_id（可选）：沙箱 ID。回退到 MAILTRAP_SANDBOX_ID。
• message_id（必需）：包含附件的沙箱消息的 ID
• attachment_id（必需）：要获取的附件的 ID

list-sending-domains

列出发送域名及其 DNS 验证状态。

参数：

• 无需参数

get-sending-domain

通过 ID 获取发送域名及其验证状态（包括 DNS 记录）。通过将 include_setup_instructions 设置为 true，可以选择包含 DNS 设置说明。

参数：

• sending_domain_id（必需）：发送域名 ID
• include_setup_instructions（可选）：如果为 true，则将 DNS 设置说明附加到响应中。默认：false

create-sending-domain

创建一个新的发送域名。创建后，添加 DNS 记录以验证域名（使用带有 include_setup_instructions: true 的 get-sending-domain 查看记录）。

参数：

• domain_name（必需）：域名（例如 example.com）

delete-sending-domain

删除一个发送域名。

参数：

• sending_domain_id（必需）：要删除的发送域名 ID

send-sending-domain-setup-instructions

将发送域名的 DNS 设置说明通过邮件发送到给定地址。用于将 DNS 记录转发给 DevOps 团队成员。

参数：

• sending_domain_id（必需）：发送域名 ID
• email（必需）：要将 DNS 设置说明发送到的邮件地址

list-suppressions

列出或搜索抑制项（硬退回、垃圾邮件投诉、取消订阅、手动导入）。每次调用最多返回 1000 个结果。

参数：

• email（可选）：邮件筛选器。仅返回与此地址匹配的抑制项。

delete-suppression

通过 ID 删除抑制项。Mailtrap 将恢复向此邮件的投递，除非它再次被抑制。

参数：

• suppression_id（必需）：要删除的抑制项的 ID

list-webhooks

列出为账户配置的所有 webhook。以 JSON 格式返回完整的 webhook 记录。

参数：

• 无需参数

get-webhook

通过 ID 获取单个 webhook。以 JSON 格式返回完整的 webhook 记录。注意：signing_secret 不在此处返回——它仅在 create-webhook 的响应中可用。

参数：

• webhook_id（必需）：要获取的 webhook 的 ID

create-webhook

创建一个 webhook。响应包含用于验证 webhook 有效负载签名的 signing_secret——此密钥仅在创建时返回，因此请立即存储。如果丢失，请重新创建 webhook。

参数：

• url（必需）：Mailtrap 将向其 POST webhook 事件的 URL
• webhook_type（必需）："email_sending" 或 "audit_log"
• active（可选，布尔值）：默认为 true
• payload_format（可选）："json" 或 "jsonlines"。默认为 "json"
• sending_stream（可选，仅 email_sending）："transactional" 或 "bulk"
• event_types（可选，仅 email_sending）：delivery、soft_bounce、bounce、suspension、unsubscribe、open、spam_complaint、click、reject 的数组
• domain_id（可选，仅 email_sending）：要将此 webhook 范围限定到的发送域名 ID

update-webhook

更新 webhook 的可变字段。webhook_type、sending_stream 和 domain_id 在创建后无法更改——如果需要更改这些，请重新创建 webhook。

参数：

• webhook_id（必需）：要更新的 webhook 的 ID
• url（可选）：新的 webhook URL
• active（可选，布尔值）：启用或禁用 webhook
• payload_format（可选）："json" 或 "jsonlines"
• event_types（可选，仅 email_sending）：delivery、soft_bounce、bounce、suspension、unsubscribe、open、spam_complaint、click、reject 的数组

delete-webhook

通过 ID 永久删除 webhook。返回已删除的 webhook 记录。

参数：

• webhook_id（必需）：要删除的 webhook 的 ID

get-contact

通过 ID 或邮件获取联系人。返回完整的联系人记录（列表成员资格、状态、自定义字段）。

参数：

• contact_identifier（必需）：联系人 ID 或邮件地址

create-contact

创建一个新联系人。

参数：

• email（必需）：邮件地址
• fields（可选）：按合并标记键控的自定义字段值（例如 first_name）。字符串、数字或布尔值
• list_ids（可选）：要将此联系人订阅到的联系人列表的 ID
• unsubscribed（可选，布尔值）：以 unsubscribed 状态创建联系人

update-contact

更新由 ID 或邮件标识的现有联系人。list_ids 替换联系人的完整成员资格集；list_ids_included/list_ids_excluded 在不干扰其余部分的情况下添加/删除。

参数：

• contact_identifier（必需）：联系人 ID 或邮件
• email（可选）：新的邮件地址
• fields（可选）：按合并标记键控的自定义字段值
• list_ids（可选）：用此确切列表替换成员资格集
• list_ids_included（可选）：要添加的列表 ID（附加）
• list_ids_excluded（可选）：要删除的列表 ID
• unsubscribed（可选，布尔值）：设置为 unsubscribed (true) 或 subscribed (false)

delete-contact

通过 ID 或邮件永久删除联系人。当 API 响应包含一个时，返回已删除的联系人记录；否则返回确认有效负载。

参数：

• contact_identifier（必需）：联系人 ID 或邮件

create-contact-event

针对联系人（通过 ID 或邮件）记录联系人事件。用于触发联系人列表自动化。

参数：

• contact_identifier（必需）：联系人 ID 或邮件
• name（必需）：事件名称（匹配自动化触发器）
• params（必需）：任意键/值对的对象。值可以是字符串、数字、布尔值或 null

list-contact-lists

列出账户的所有联系人列表。

参数：

• 无需参数

get-contact-list

通过 ID 获取联系人列表。

参数：

• list_id（必需）：要获取的联系人列表的 ID

create-contact-list

创建一个新的联系人列表。

参数：

• name（必需）：新列表的名称

update-contact-list

重命名现有的联系人列表。

参数：

• list_id（必需）：联系人列表的 ID
• name（必需）：列表的新名称

delete-contact-list

通过 ID 永久删除联系人列表。

参数：

• list_id（必需）：要删除的联系人列表的 ID

list-contact-fields

列出账户的所有联系人字段定义。

参数：

• 无需参数

get-contact-field

通过 ID 获取联系人字段定义。

参数：

• field_id（必需）：联系人字段的 ID

create-contact-field

创建一个新的联系人字段定义。merge_tag 在账户内必须唯一，并用作模板变量中的占位符名称。

参数：

• name（必需）：显示名称（例如“First Name”）
• merge_tag（必需）：唯一的占位符名称（例如 first_name）
• data_type（必需）：text、number、boolean、date 之一

update-contact-field

更新联系人字段定义。可以更改 name、merge_tag 和 data_type 的任意组合。

参数：

• field_id（必需）：联系人字段的 ID
• name（可选）：新的显示名称
• merge_tag（可选）：新的合并标记（必须保持唯一）
• data_type（可选）：text、number、boolean、date 之一

delete-contact-field

通过 ID 永久删除联系人字段定义。

参数：

• field_id（必需）：要删除的联系人字段的 ID

create-contact-import

批量导入联系人。返回一个导入作业记录；使用 get-contact-import 轮询其状态。

参数：

• contacts（必需）：联系人条目数组。每个条目需要：
  • email（必需）：联系人邮件地址
  • fields（可选）：按合并标记键控的自定义字段值（字符串或数字值）
  • list_ids_included（可选）：要将联系人添加到的列表 ID
  • list_ids_excluded（可选）：要从中删除联系人的列表 ID

get-contact-import

获取联系人导入作业的状态（已创建/已开始/已完成/失败），包含已创建/已更新/超出限制的计数。

参数：

• import_id（必需）：联系人导入作业的 ID

create-contact-export

导出匹配一组 AND 组合筛选器的联系人。返回一个导出作业记录；使用 get-contact-export 轮询状态，以在 status 为 finished 后检索下载 URL。

参数：

• filters（必需）：筛选器对象数组。每个包含：
  • name（必需）：要筛选的字段（list_id、subscription_status、email 等）
  • operator（必需）：equal、not_equal、contains、not_contains、is_empty、is_not_empty 之一
  • value（必需）：比较值（字符串、数字、布尔值或数组）

get-contact-export

获取联系人导出作业的状态。一旦 status 为 finished，url 字段将保存 CSV 下载链接。

参数：

• export_id（必需）：联系人导出作业的 ID

list-accounts

列出当前 API 令牌可以访问的 Mailtrap 账户，以及每个账户的访问级别。

参数：

• 无需参数

get-billing-usage

获取账户当前计费周期的使用情况：发送和测试计划、限制和当前计数。

参数：

• 无需参数

list-account-accesses

列出账户的账户访问权限（用户、邀请、API 令牌）。可选筛选器将结果缩小到特定资源。需要账户管理员/所有者权限。

参数：

• domain_uuids（可选）：按发送域名 UUID 筛选（字符串数组）
• inbox_ids（可选）：按沙箱收件箱 ID 筛选（字符串数组）
• project_ids（可选）：按沙箱项目 ID 筛选（字符串数组）

remove-account-access

通过 ID 删除账户访问权限。对于 User 说明符，这将撤销其权限；对于 Invite 或 ApiToken 说明符，它将完全删除说明符。需要管理员/所有者权限。

参数：

• account_access_id（必需）：要删除的访问记录的 ID

get-permission-resources

获取 API 令牌对其具有管理员访问权限的所有资源（收件箱、项目、域名、计费、账户），按层次结构嵌套。

参数：

• 无需参数

bulk-update-permissions

为单个账户访问权限批量创建、更新或销毁权限。现有的 (resource_type, resource_id) 对被更新；新的对被创建。在条目上设置 destroy: true 以将其删除。

参数：

• account_access_id（必需）：目标账户访问权限 ID
• permissions（必需）：权限条目数组。每个包含：
  • resource_id（必需）：资源 ID（数字或字符串）
  • resource_type（必需）：account、project、inbox、domain、billing 之一
  • access_level（可选）：admin/100 或 viewer/10
  • destroy（可选，布尔值）：当为 true 时，删除此权限而不是创建/更新它

list-api-tokens

列出账户的所有 API 令牌。

参数：

• 无需参数

create-api-token

创建一个新的 API 令牌。响应包含密钥 token 值——这是唯一一次返回完整令牌，因此请立即存储。如果丢失，请重新创建令牌。

参数：

• name（必需）：令牌的显示名称
• resources（可选）：要将令牌范围限定到的资源权限数组。每个条目包含：
  • resource_type（必需）：account、project、inbox、domain、billing 之一
  • resource_id（必需）：资源的 ID
  • access_level（必需）：100（管理员）或 10（查看者）

get-api-token

通过 ID 获取 API 令牌。仅返回元数据——密钥令牌值不在此处返回（仅来自 create-api-token / reset-api-token）。

参数：

• api_token_id（必需）：API 令牌的 ID

reset-api-token

通过 ID 重置（轮换）API 令牌。响应包含新的密钥 token 值——仅在此调用时返回，因此请立即存储。先前的令牌将失效。

参数：

• api_token_id（必需）：要重置的 API 令牌的 ID

delete-api-token

通过 ID 永久删除 API 令牌。删除后，令牌将无法再进行身份验证。

参数：

• api_token_id（必需）：要删除的 API 令牌的 ID

list-sub-accounts

列出组织中的子账户。需要 MAILTRAP_ORGANIZATION_ID 环境变量和子账户管理权限。

参数：

• 无需参数

create-sub-account

在组织下创建一个新的子账户。需要 MAILTRAP_ORGANIZATION_ID 环境变量和子账户管理权限。

参数：

• name（必需）：新子账户的显示名称

开发

1. 克隆仓库：

git clone https://github.com/mailtrap/mailtrap-mcp.git
cd mailtrap-mcp

2. 安装依赖项：

npm install

使用 Claude Desktop 或 Cursor 配置

[!TIP] 在 设置 部分查看配置文件的位置。

添加以下配置：

{
  "mcpServers": {
    "mailtrap": {
      "command": "node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

如果您使用 asdf 管理 Node.js，则应使用可执行文件的绝对路径：

（Mac 示例）

{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users/<username>/.asdf/shims/node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "PATH": "/Users/<username>/.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
        "ASDF_DATA_DIR": "/Users/<username>/.asdf",
        "ASDF_NODEJS_VERSION": "20.6.1",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

VS Code

[!TIP] 在 设置 部分查看配置文件的位置。

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "node",
        "args": ["/path/to/mailtrap-mcp/dist/index.js"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "[email protected]",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

测试

针对真实 Mailtrap 运行工具

有两种方法可以针对真实 Mailtrap 账户端到端地练习工具：用于交互式探索的 MCP Inspector 浏览器 UI，或用于从 shell 进行一次性调用的 CLI 模式。

两者都需要先构建 bundle：

npm run build

并在您的 shell 中导出 MAILTRAP_API_TOKEN + MAILTRAP_ACCOUNT_ID（mcp:cli 脚本将两者转发到生成的服务器）。

浏览器 UI

npm run dev

Inspector 打印一个类似 http://localhost:6274 的 URL。打开它，切换到工具选项卡，选择一个工具（例如 get-template），以 JSON 格式填写参数，然后点击运行。Mailtrap 响应将显示在下面的面板中。

CLI

对于没有 UI 的一次性调用，请使用 npm run mcp:cli。在 -- 之后传递 Inspector 的 CLI 标志，以便 npm 逐字转发它们：

# List all tools
npm run mcp:cli -- --method tools/list

# Call a tool — flags after the `--`
npm run mcp:cli -- \
  --method tools/call \
  --tool-name get-template \
  --tool-arg template_id=12345

# Multiple --tool-arg flags for tools with several params
npm run mcp:cli -- \
  --method tools/call \
  --tool-name send-sending-domain-setup-instructions \
  --tool-arg sending_domain_id=3938 \
  --tool-arg [email protected]

运行 MCPB 服务器

# Run the MCPB server directly
node dist/mcpb-server.js

# Or use the provided binary
mailtrap-mcpb-server

[!TIP] 对于使用 MCP Inspector 进行开发：

npm run dev:mcpb

错误处理

此服务器使用符合 MCP 约定的结构化错误处理：

• VALIDATION_ERROR：输入验证失败
• CONFIGURATION_ERROR：缺少或无效的配置
• EXECUTION_ERROR：运行时执行错误
• TIMEOUT：操作超时（默认 30 秒）

错误包含可操作的提示，并以结构化形式记录。

安全

• 通过 Zod 模式验证输入
• 安全处理环境变量
• 操作超时保护（30 秒）
• 错误输出中敏感细节被清理

日志记录

结构化 JSON 日志，级别：INFO、WARN、ERROR、DEBUG。

通过设置 DEBUG=true 启用调试日志记录。

# Example: enable debug logging
DEBUG=true node dist/mcpb-server.js

重要：服务器将日志写入 stderr，以便 stdout 保持为 JSON-RPC 帧保留。这可以防止主机因交错日志而遇到 JSON 解析错误。

使用 jq 的日志分析示例：

# Filter error logs
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "error")'

# Filter debug logs
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "debug")'

故障排除

常见问题：

1. 缺少 API 令牌：确保设置了 MAILTRAP_API_TOKEN
2. 沙箱不工作：在工具调用中提供 test_inbox_id 或设置 MAILTRAP_TEST_INBOX_ID 环境变量
3. 超时错误：检查网络连接和 Mailtrap API 状态
4. 验证错误：确保提供了所有必需字段

贡献

欢迎在 GitHub 上提交错误报告和拉取请求。该项目旨在成为一个安全、友好的协作空间，贡献者应遵守 行为准则。

许可证

该软件包根据 MIT 许可证 的条款作为开源软件提供。

行为准则

参与 Mailtrap 项目的代码库、问题跟踪器、聊天室和邮件列表的每个人都应遵守 行为准则。