MailProbe

mailprobe-mcp

MailProbe API 的官方 Model Context Protocol 服务。你的 AI 助手可以实时检查电子邮件地址是否存在且能够接收邮件，无需发送任何内容：既可以检查单个地址，也可以在发起营销活动前检查一组地址。验证在法国的 OVHcloud 服务器上运行，API 不会存储任何地址。

安装 · 工具 · 工作方式 · 开发

有两种方式可以连接，使用的工具相同：

• MailProbe 运行在 https://mailprobe.dev/mcp 的远程服务，适用于能够连接远程服务并发送请求头的客户端：无需安装；
• 此软件包的本地服务，npx -y mailprobe-mcp，适用于在你的电脑上启动服务的客户端。

此代码库还包含 Claude Code 插件，以及一项技能，用于指导助手如何解读结果以及如何处理一组地址。

安装

1. 在 mailprobe.dev 上创建账户。账户附带 100 个免费额度；更多信息请参阅定价。
2. 在账户的 Developer 下创建 API 密钥，密钥以 mp_live_ 开头。MailProbe 只会在创建时显示一次密钥。
3. 将其中一个服务添加到你的 MCP 客户端。

远程服务

密钥应放在 Authorization 请求头中。在 Claude Code 中：

claude mcp add --transport http mailprobe https://mailprobe.dev/mcp --header "Authorization: Bearer mp_live_..."

在 Cursor 中，配置文件为 .cursor/mcp.json：

{
  "mcpServers": {
    "mailprobe": {
      "url": "https://mailprobe.dev/mcp",
      "headers": { "Authorization": "Bearer mp_live_..." }
    }
  }
}

任何能够连接远程 MCP 服务并发送请求头的其他客户端，配置方式都相同。

本地服务

密钥应放在 MAILPROBE_API_KEY 环境变量中，服务需要 Node.js 22 或更高版本。在 Claude Desktop 和其他通过 JSON 文件配置的客户端中：

{
  "mcpServers": {
    "mailprobe": {
      "command": "npx",
      "args": ["-y", "mailprobe-mcp"],
      "env": { "MAILPROBE_API_KEY": "mp_live_..." }
    }
  }
}

Claude 和 ChatGPT 应用只能通过 OAuth 登录连接远程服务，而 MailProbe 尚未提供此功能。Claude Desktop 使用上面的本地服务；在其他地方，可通过 Zapier MCP 使用 MailProbe。

Claude Code 插件

此插件将 Claude Code 连接到远程服务，并添加一项技能，指导助手如何解读结果、每次调用的费用，以及如何处理一组地址。

/plugin marketplace add jamalofski/mailprobe-mcp
/plugin install mailprobe@mailprobe

启用插件时，Claude Code 会要求输入 API 密钥，并将其保存在系统的凭据存储区，而非设置文件中。稍后设置密钥时，运行 /plugin configure mailprobe@mailprobe，或者打开 /plugin，选择 Installed 选项卡中的 mailprobe，再选择 Configure options。你手动添加的、地址相同的远程服务优先于插件中的服务。

对于其他可加载 SKILL.md 技能的 Agent，添加上面的任一服务，并单独使用该技能：本代码库中的 plugin/skills/mailprobe/SKILL.md，也列于 Agensi。

然后提出你的需求：“[email protected] 存在吗？”，“发送新闻简报前检查 contacts.csv 中联系人的地址”，“这些注册用户中哪些使用了一次性邮箱？”。

工具

工具	功能
verify_emails	验证 1 到 20 个地址，并按给定顺序为每个地址返回一项结果：status（valid、invalid、risky 或 unknown）、0 到 100 的 score、对于无法明确确认可投递的判定所给出的 reason、disposable、role_based、free_provider 和 catch_all 标记，以及针对可能拼写错误给出的 did_you_mean
get_credits	返回 API 密钥账户剩余的额度

结果字段与 API 中的字段相同：请参阅 API 文档。

工作方式

• 不会向该地址发送邮件。 MailProbe 会检查地址语法和域名的邮件服务器，然后询问邮件服务器该邮箱是否存在，到此为止。
• 不会存储任何内容。 通过 API 验证的地址会在内存中处理，响应发送后便不复存在。后续请求不会重复使用任何结果。
• 两个服务提供相同的工具。 本地服务逐字沿用远程服务的指令和工具定义，并以相同方式表达拒绝。它不会在助手与 API 之间添加任何内容：它会将地址发送到 https://mailprobe.dev/api/v1 并返回结果。
• 额度。 每个实际探测的地址消耗 1 个额度，与 API 一样从你的账户扣除。同一次调用中重复的地址、格式不正确的条目、调用返回时仍未得出判定的地址，以及邮件服务器拒绝连接的地址，均不消耗额度。get_credits 免费。
• 速率限制。 API 对每个 API 密钥每分钟接受 60 次调用，一次包含 20 个地址的调用计为 1 次。被拒绝的调用会返回需要等待的秒数。本地服务会自行等待并重试，最多两次；仅当等待时间不超过 30 秒且调用仍能及时返回时才会重试，否则助手会收到需要等待的时长。
• 响应时间。 两个服务的调用都会在约 55 秒内返回，因为 MCP 客户端会在工具调用开始 1 分钟后放弃。此时仍未得出判定的地址会以 unknown 状态和 timeout 原因返回，不收取费用：再次提交即可。
• 长列表。 一次调用最多处理 20 个地址，因此助手会分多次调用发送列表。地址数量超过几百时，账户的批量验证页面是更合适的工具：可粘贴最多包含 500 个地址的列表，或上传最多包含 250,000 个地址的 CSV 或 TXT 文件，在后台进行验证。
• 错误。 拒绝信息会以助手可据此采取行动的句子返回：需要设置的密钥、需要购买的额度、需要等待的时长。
• 不设置密钥。 本地服务会启动并列出其工具；调用时会说明如何设置 MAILPROBE_API_KEY。

本地服务的每个请求都会携带 User-Agent: mailprobe-mcp/<version>。联系支持人员时请提及此信息：它可以帮助他们在 API 日志中区分你的调用。

开发

本地服务没有依赖：Node.js 会直接运行源文件。它通过 stdio 与客户端通信，并在同一进程中支持两个时代的协议：每个请求都携带协议版本的 2026-07-28 修订版，以及以 initialize 握手开始的早期修订版（2025-11-25 至 2024-11-05）。

npm test

在本地端口上使用虚假的 MailProbe API 运行测试：无需密钥，也无需网络。测试还会检查软件包、插件、技能和此 README 是否一致。

npm run check-tools

将此软件包的指令和工具定义与远程服务的内容进行比较；远程服务无需密钥即可提供这些内容。

插件

plugin/ 包含 Claude Code 插件：其清单、指向远程服务的 .mcp.json，以及技能文件 plugin/skills/mailprobe/SKILL.md。.claude-plugin/marketplace.json 是目录，可让 Claude Code 从此仓库安装插件。两者都不属于 npm 软件包。

claude plugin validate . --strict
claude --plugin-dir ./plugin

检查清单，然后从文件夹加载插件并启动会话，无需安装。版本变更后，用户会收到更新后的插件或技能：它们会随发布版本一起提供。

发布

1. 在 package.json 和 plugin/.claude-plugin/plugin.json 中设置版本，并为 CHANGELOG.md 中对应的章节添加日期。
2. 运行 npm test 和 npm run check-tools。
3. 提交更改，然后推送一个以版本号命名的标签：Publish 工作流会通过 Trusted Publishing 将软件包发布到 npm，并附上来源证明。
4. 如果技能有更改，请将其作为新版本重新上传到 Agensi 列表：将包含 SKILL.md 的 mailprobe/ 文件夹打包成 ZIP。此仓库中的任何更改都不会自动更新该列表。

资源

• MailProbe API 文档
• mailprobe.dev 上的 MCP 设置说明
• Agensi 上的 MailProbe 技能
• Model Context Protocol 规范

支持

提交 issue，或发送邮件至 [email protected]。

许可证

MIT，详见 LICENSE。