MinuteMail

MinuteMail MCP 服务

将 MinuteMail 用作 MCP（Model Context Protocol）工具：让 AI Agent 和 MCP 客户端操作临时邮箱、邮件、附件、自定义域名、团队以及用于测试邮件和身份验证流程的模拟 OAuth 身份。

• 端点： https://mcp.minutemail.co/mcp（Streamable HTTP，协议 修订版本 2025-06-18）
• 身份验证： 你的 MinuteMail API 密钥（Bearer mmak_...）。该服务是无状态代理——它自身不保存凭据、会话或本地存储；你的密钥会原样转发到 MinuteMail API，由后者执行范围和配额限制。所有状态（邮箱、邮件、身份）都存储在其背后的 MinuteMail 平台中。
• 也列于官方 MCP Registry，标识为 io.github.minutemailco/mcp-server，并列于 Smithery。

获取 API 密钥

1. 在 minutemail.co 注册（早期访问期间免费）

2. 在控制面板中创建 API 密钥

3. 将 MCP 客户端配置为通过 Authorization 标头发送该密钥：

   Authorization: Bearer mmak_XXXXXXXX

连接 MCP 客户端

Claude Code / Claude Desktop / Cursor / 任意 Streamable HTTP 客户端：

• URL：https://mcp.minutemail.co/mcp
• 标头：Authorization: Bearer mmak_...

Claude Code CLI：

claude mcp add --transport http minutemail https://mcp.minutemail.co/mcp \
  --header "Authorization: Bearer mmak_XXXXXXXX"

Claude Desktop / 使用 mcpServers JSON 配置的客户端（例如 claude_desktop_config.json / ~/.cursor/mcp.json）：

{
  "mcpServers": {
    "minutemail": {
      "type": "http",
      "url": "https://mcp.minutemail.co/mcp",
      "headers": {
        "Authorization": "Bearer mmak_XXXXXXXX"
      }
    }
  }
}

某些客户端（较旧版本的 Claude Desktop）在其 JSON 配置中仅支持本地 stdio 服务。如果你的客户端不接受 type: "http"，请使用内置的远程/连接器 UI，并填写上方的 URL 和标头，或者运行 mcp-remote 作为 stdio 桥接：

{
  "mcpServers": {
    "minutemail": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.minutemail.co/mcp",
        "--header",
        "Authorization: Bearer mmak_XXXXXXXX"
      ]
    }
  }
}

如需按步骤操作，请参阅文档： docs.minutemail.co/mcp/getting-started。

原始 JSON-RPC（客户端底层的操作方式）：

curl -s https://mcp.minutemail.co/mcp \
  -H 'Authorization: Bearer mmak_XXXXXXXX' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"mailboxes.create","arguments":{"expiresIn":30}}}'

工具（39）

每个工具都与 MinuteMail API 的一个路由一一对应。所有调用都需要 Bearer API 密钥；写入操作需要相应的范围（mailboxes、 domains、team、identities）。

邮箱（mailboxes 范围）

工具	用途
mailboxes.list	列出活跃邮箱（可选：按完整地址查询）
mailboxes.create	创建邮箱（可选：TTL、域名、恢复标签）
mailboxes.get / mailboxes.delete	获取 / 删除一个邮箱
mailboxes.delete_bulk	按 ID 删除多个邮箱
mails.list / mails.inject	列出邮件 / 模拟收到一封邮件（支持 multipart，含附件）
mails.get / mails.delete / mails.delete_bulk	读取 / 删除邮件
attachments.list / attachments.add / attachments.get / attachments.delete / attachments.delete_bulk	附件 CRUD

已归档邮箱（mailboxes 范围）

archived.list、archived.get、 archived.delete、archived.reactivate。

自定义域名（domains 范围）

domains.list、domains.register、domains.verify、domains.delete。

团队（team 范围）

team.members.list、team.members.add、team.members.get、team.members.delete、 team.invitations.create、team.invitations.list、team.invitations.delete。

模拟身份和 OAuth 客户端（identities 范围）

identities.list、identities.create、identities.update、identities.get、 identities.delete、oauth.clients.list、oauth.clients.create、 oauth.clients.get、oauth.clients.delete、oauth.clients.rotate_secret。 identities.update 会更新个人资料字段、isActive（激活／停用）、 emailVerified（决定 email_verified 声明的值），以及自定义 claims； 这些自定义声明会合并到签发的 ID 令牌和 userinfo 响应中。

工具结果会以 MCP 文本内容的形式返回，并包含 API 的 JSON 响应。非 2xx 响应会作为 isError: true 结果返回，其中包含 HTTP 状态码和响应正文（401 表示密钥无效，403 表示范围／域名问题，429 表示配额超限并附带剩余数量，502 表示上游服务不可用）。

典型的 Agent 工作流

mailboxes.create (expiresIn 30)
        ↓
your app under test sends a verification email to the mailbox address
        ↓
mails.list → mails.get (extract the code / link)
        ↓
assert the flow completed — the mailbox expires on its own

自托管

该服务是一个位于 scratch 镜像中的 Go 静态二进制文件（约 7 MB）：

docker run -p 8080:8080 \
  -e API_BASE=https://api.minutemail.co \
  ghcr.io/minutemailco/mcp-server:latest
# or from Docker Hub:
docker run -p 8080:8080 \
  -e API_BASE=https://api.minutemail.co \
  chrptvn/minutemail-mcp:latest

自托管仍需使用 MinuteMail API 密钥——该服务是托管 API 的无状态代理，并非独立实现。它不会保留会话或本地数据；每个邮箱、邮件和身份都由它转发请求的 MinuteMail API 存储。

环境变量	默认值	用途
PORT	8080	监听端口
API_BASE	http://api-gateway:80	MinuteMail API 基础 URL（在集群外使用 https://api.minutemail.co）
LOG_LEVEL	warn	debug／info／warn／error
LOG_FORMAT	json	json／text
PROFILE	dev	部署配置标签

GET /health 用于存活检查；GET /metrics 用于获取 Prometheus 计数器。 MCP 不提供 API 密钥管理功能——请在 Web 应用中管理密钥。

开发

Go 1.23、标准库和 prometheus/client_golang。

go test ./...     # unit tests
go vet ./...
go run .          # local server on :8080

许可证

MIT — © MinuteMail.co