mailsocket

mailsocket — MCP 服务

一个 MCP 服务，将 mailsocket 作为原生工具提供给 AI 编码 Agent，让 Agent 能创建临时收件箱，并等待 OTP 或魔法链接，无需编写任何轮询代码。它封装了 Python SDK——无需额外的 HTTP 客户端，也无需重新实现轮询。

功能

工具	Agent 可获得的内容
create_inbox(label?)	一个全新的收件箱 id 和 address
wait_for_otp(inbox_id, timeout?=60, min_confidence?=0, since?)	核心功能——阻塞等待（有时限：请求的截止时间在本地最多为 120s，在远程服务上最多为 55s），并返回 OTP 字符串、置信度、主题／发件人／id／received_at。默认省略 since：仅匹配此调用后到达的邮件。
wait_for_link(inbox_id, timeout?=60, since?)	提取的魔法链接（仅返回，不会访问）以及主题／发件人／id／received_at。默认省略 since：仅匹配此调用后到达的邮件。
list_inboxes(limit?, cursor?)	此密钥所拥有的一个页面收件箱（服务端默认每页 25 条），以及 next_cursor／has_more
list_messages(inbox_id, has_otp?, subject_contains?, sender?, limit?, cursor?)	一个页面的邮件，可选筛选（服务端默认每页 25 条），以及 next_cursor／has_more
get_latest(inbox_id)	最新邮件，不会阻塞
send_test_code(inbox_id)	直接向收件箱放入一封包含示例 OTP 的邮件（不经过邮件服务器），并返回其 message_id 和 sent_at，这样你无需真实邮件即可检查等待循环。每个收件箱每小时 5 次／每个账户每小时 20 次。
delete_inbox(inbox_id)	用完后删除收件箱

SDK 错误（AuthError／NotFound／RateLimited／WaitTimeout）会转换为清晰的 MCP 工具错误——不会显示堆栈跟踪，也不会回显 API 密钥。

重用收件箱

create_inbox 无需 since——新收件箱只会有新邮件。默认情况下，wait_for_otp／wait_for_link 会完全省略 since，因此服务端只匹配调用之后（即请求开始时间之后）到达的邮件。但如果你重用已有收件箱（例如请求第二个 OTP／链接），请显式传入 since：否则，不带 since 的调用会正确忽略收件箱中已有的邮件，这适用于大多数重用场景；但如果你确实想要捕获工具调用前已到达的代码，请传入触发新邮件前的时间（ISO8601 或 Unix 秒），或传入你上次看到的邮件 id（msg_...，表示“仅匹配此邮件之后的邮件”）。这两个工具都会在匹配的邮件上返回 id／received_at，因此你可以将 since=<id> 传给同一收件箱的下一次调用。

无需真实邮件即可测试循环

send_test_code 不会经过邮件服务器，因此工具返回时，代码已在收件箱中。先设置一个截止点：使用 get_latest 返回的 id（如果收件箱为空，则使用 since=0），或使用当前时间。然后调用 send_test_code(inbox_id)，再调用 wait_for_otp(inbox_id, since=<that cutoff>)。如果不传 since，等待过程只会看到等待期间到达的邮件，因此会错过测试代码。

要求

• Python 3.10+
• mailsocket API 密钥——可从 控制面板 获取，或通过 POST /api/v1/agents/register 获取。

安装

使用 uv 无需安装：

uvx mailsocket-mcp

也可以使用 pip 安装：

pip install mailsocket-mcp
mailsocket-mcp

无论哪种方式，它都会从环境中读取 MAILSOCKET_API_KEY（以及可选的 MAILSOCKET_BASE_URL）。如果缺少密钥，程序会显示清晰的提示并以状态码 2 退出；密钥绝不会写入日志。

在 MCP 客户端中注册

Claude Desktop / Cursor

将以下内容添加到客户端的 MCP 配置文件中——Claude Desktop 使用 claude_desktop_config.json，Cursor 使用 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "mailsocket": {
      "command": "uvx",
      "args": ["mailsocket-mcp"],
      "env": {
        "MAILSOCKET_API_KEY": "ms_live_..."
      }
    }
  }
}

Claude Code CLI

claude mcp add mailsocket -e MAILSOCKET_API_KEY=ms_live_... -- uvx mailsocket-mcp

任何其他兼容 MCP 的客户端也可以采用相同方式：通过 stdio 指向 mailsocket-mcp 可执行文件（或 uvx mailsocket-mcp），并通过环境变量传递密钥。

远程服务（无需安装）

相同的工具也通过 Streamable HTTP 托管在 https://mcp.mailsocket.app/mcp。请在每个请求中通过请求头传递密钥： Authorization: Bearer ms_live_...。切勿将密钥放入 URL；使用 ?api_key= 的请求会被拒绝。

Claude Code CLI

claude mcp add --transport http mailsocket https://mcp.mailsocket.app/mcp \
  --header "Authorization: Bearer ms_live_..."

Cursor（~/.cursor/mcp.json）

{
  "mcpServers": {
    "mailsocket": {
      "url": "https://mcp.mailsocket.app/mcp",
      "headers": { "Authorization": "Bearer ms_live_..." }
    }
  }
}

VS Code（.vscode/mcp.json）

{
  "servers": {
    "mailsocket": {
      "type": "http",
      "url": "https://mcp.mailsocket.app/mcp",
      "headers": { "Authorization": "Bearer ms_live_..." }
    }
  }
}

任何能够设置自定义 HTTP 请求头的客户端也可以采用相同方式（OpenAI Agents SDK、n8n MCP Client 节点或你自己的代码）。

请注意：

• Claude.ai、Claude Desktop 连接器和 Smithery 需要 OAuth，该功能已列入计划，但尚不可用。在此之前，请在这些客户端（Claude Desktop）中使用上文的本地 stdio 服务，或使用支持请求头的客户端。
• 在远程服务上，wait_for_otp / wait_for_link 每次调用最多等待 55s，以确保每个响应都不超过代理超时时间。超时后请再次调用该工具。
• 服务是无状态的：无需维持会话，每个请求都会单独进行身份验证。服务本身没有密钥，只会使用你的密钥，并受你正常的 API 速率限制约束。
• 自托管：mailsocket-mcp-http 运行相同的服务（环境变量见 mailsocket_mcp/remote.py）。

环境变量

变量	必需	描述
MAILSOCKET_API_KEY	是（机密）	你的 mailsocket API 密钥（ms_live_...）。
MAILSOCKET_BASE_URL	否	覆盖 API 基础 URL。默认为 https://dash.mailsocket.app/api/v1。

开发

pip install -e ".[dev]"
pytest

测试不会发出任何外部请求或实时 API 请求。SDK 客户端使用模拟对象，远程传输测试则会与 127.0.0.1 上的本地模拟上游服务通信。

更新日志

• 0.4.1 — 要求 mailsocket>=0.3.1：不带 since 调用 wait_for_otp / wait_for_link 时，不再漏掉 SDK 内部多次长轮询调用之间到达的消息（每次后续调用都会发送服务端在 Mailsocket-Wait-Since 中报告的截止时间）。工具签名没有变化。
• 0.4.0 — 新增 send_test_code(inbox_id) 工具（stdio 和托管的远程服务均支持，且受与其他非等待工具相同的每密钥上限约束）：无需经过邮件服务器，即可向你自己的收件箱发送一封示例 OTP 邮件。要求 mailsocket>=0.3.0（Client.send_test_code）。
• 0.3.0 — 行为变更（通过 mailsocket>=0.2.0）：wait_for_otp / wait_for_link 默认不再传递 since，而是省略该参数（表示“收件箱中的任何已有消息”）。旧默认值可能会返回复用收件箱中已有的过期 OTP/链接；新默认值只会匹配调用后到达的消息。显式传入 since=0 可保留旧行为。 托管服务（mcp.mailsocket.app，从仓库部署，无需发布新的 PyPI 版本）：每个密钥的并发等待数从 3 提高至 10（即 Pro 方案上限；API 仍会执行各方案自身的上限），共享等待池从 16 扩大至 32，以配合后端提高后的等待容量（全局 64）。
• 0.2.3 — wait_for_otp / wait_for_link 支持可选的 since（ISO8601、Unix 秒数或消息 ID），因此复用收件箱时会返回新的代码；结果包含消息 id 和 received_at。
• 0.2.2 — 依赖 mailsocket>=0.1.3（底层 Python SDK 中更严格的 _seg ID 验证）。