文档

四步即可让你的智能体
拥有一个收件箱。

连接任意电子邮件账户，把一个 URL 粘贴到支持 OAuth 的 MCP 客户端中并授权。不支持 OAuth 的客户端则改用 API 密钥。下方提供完整的工具参考和连接指南。

快速开始 OAuth（claude.ai）工具参考服务商支持

快速开始

几分钟内即可上手运行。

无需 SDK。MCPEmails 通过 HTTP 讲标准 MCP，因此可接入任何兼容 MCP 的智能体。

01注册并连接收件箱

创建账户并连接 Gmail

在 mcpemails.com 注册，然后前往仪表盘 → 收件箱 → 连接收件箱。选择 Gmail、Outlook、iCloud、Fastmail 或任何 IMAP 收件箱，然后完成 OAuth 流程或粘贴一个应用密码。你的收件箱在一分钟内即可就绪。

连接你的收件箱 →

02创建 API 密钥

为你的智能体生成一个 bearer 令牌

在仪表盘 → API 密钥中，点击“创建密钥”。为它命名，选择你的智能体所需的权限范围（read:email 和/或 send:email），然后复制密钥。它仅显示一次。

# Your key looks like this:
mcpe_live_AbCdEfGhIjKlMnOpQrStUvWxYz123456

03将 MCPEmails 添加到你的智能体

把 MCP 端点粘贴到你的客户端中

在下方选择你的客户端对应的标签页。支持 OAuth 2.0 的 MCP 客户端（claude.ai、Claude Desktop、Cursor 等）只需粘贴 URL 并授权，无需 API 密钥。不支持 OAuth 的客户端以及脚本化访问，则使用第 02 步中的 API 密钥。

json

# OAuth-capable clients (claude.ai, Claude Desktop, Cursor…)
# No API key required. Paste the URL, click Connect, authorize.
#
# Example: claude.ai
#   1. Go to claude.ai → Customize → Connectors
#   2. Click "Add connector" and paste this URL:
#
#        https://www.mcpemails.com/api/mcp
#
#   3. Click Connect and sign in with your mcpemails account.
#   4. All six tools are live immediately.
#
# Claude Desktop and Cursor follow the same OAuth flow when
# the server URL is configured in their MCP settings.

04发起你的第一次调用

让你的智能体检查你的收件箱

无需复制粘贴收件箱 UUID。你的智能体会先调用 list_inboxes 来发现每一个已连接的收件箱及其 UUID，然后你只需说：“检查我的收件箱并总结最近 5 封未读邮件。”

# The agent calls list_inboxes first, so no hardcoded UUIDs.
# System prompt (optional, for multi-inbox setups):
You have access to email via MCPEmails.
Start by calling list_inboxes to discover available inboxes.

端点

一个 URL，标准 MCP。

所有流量都发往单个 Streamable HTTP 端点。使用来自仪表盘的 bearer 令牌进行身份验证。

POSThttps://www.mcpemails.com/api/mcp

发送一个 JSON-RPC 2.0 请求体。支持的方法：initialize、tools/list、tools/call。

传输：Streamable HTTP（MCP 2025-06-18）

认证：Authorization: Bearer <api-key>

速率限制：每个密钥 100 次/分钟 · 1,000 次/小时 · 10,000 次/天

响应格式：JSON-RPC 2.0

初始化握手

bash

curl -X POST https://www.mcpemails.com/api/mcp \
  -H "Authorization: Bearer mcpe_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "clientInfo": { "name": "my-agent", "version": "1.0" },
      "capabilities": {}
    }
  }'

OAuth 连接

对支持 OAuth 的客户端零配置。

支持 OAuth 2.0 的 MCP 客户端（claude.ai、Claude Desktop、Cursor 等）会通过授权码 + PKCE 自动连接。无需 API 密钥，无需配置文件。粘贴 URL 并点击连接。

第 1 步：前往 claude.ai → 自定义 → 连接器 → 添加连接器

第 2 步：把 https://www.mcpemails.com/api/mcp 粘贴为服务器 URL

第 3 步：点击连接。MCPEmails 会打开一个授权界面

第 4 步：用你的 mcpemails 账户登录并批准访问

完成：全部六个工具已上线。claude.ai 会自动刷新令牌

底层工作原理

claude.ai 通过 RFC 7591 动态客户端注册自行注册，因此你永远不必预先注册客户端 ID。

授权使用 OAuth 2.0 授权码 + PKCE（RFC 7636），因此从不传输任何客户端密钥。

令牌的权限范围严格限定为你所批准的权限：read:email 和/或 send:email。

使用不支持 OAuth 的客户端？在仪表盘 → API 密钥中创建一个 API 密钥，并将其作为 bearer 令牌传递。API 密钥连接和 OAuth 连接使用同一个 MCP 端点和同样的六个工具。

工具参考

六个工具。满足你智能体所需的全部邮件操作。

先用 list_inboxes 发现可用的收件箱及其 UUID。其余五个工具各需要一个由该调用返回的 inbox_id。点击“显示示例”可查看完整的请求和响应。

list_inboxesread:email list_inboxread:email read_emailread:email search_emailsread:email send_emailsend:email reply_to_emailsend:email

list_inboxesread:email

返回当前 API 密钥或 OAuth 令牌可访问的所有收件箱。先调用此工具以发现 inbox_id 值，从而无需从仪表盘复制粘贴 UUID。

无参数。使用空的参数对象进行调用： {}

list_inboxread:email

从已连接的收件箱列出邮件摘要，最新的在前。支持分页、文件夹选择和未读筛选。

参数	类型	必需	说明
`inbox_id`	string (uuid)	必需	要列出的收件箱的 UUID。先调用 list_inboxes 以发现可用的收件箱 ID。
`limit`	integer	可选	返回的最大结果数。默认 20，最大 100。
`offset`	integer	可选	从零开始的分页偏移量。默认 0。
`folder`	string	可选	要列出的文件夹。默认为 "INBOX"。其他取值："SENT"、"DRAFTS"、"TRASH"。
`unread_only`	boolean	可选	仅返回未读邮件。默认 false。

read_emailread:email

按 ID 获取单封邮件的完整内容，包括纯文本正文、可选的清理过的 HTML，以及可选的附件数据。

参数	类型	必需	说明
`inbox_id`	string (uuid)	必需	包含该邮件的收件箱的 UUID。调用 list_inboxes 以获取可用的收件箱 ID。
`message_id`	string	必需	来自 list_inbox 或 search_emails 的服务商邮件 ID。
`include_html`	boolean	可选	包含清理过的 HTML 正文。默认 false。
`include_attachments`	boolean	可选	包含 base64 附件数据。默认 false。
`mark_as_read`	boolean	可选	获取后将邮件标记为已读。默认 false。

search_emailsread:email

使用服务商原生查询语法搜索收件箱。Gmail 支持 Gmail 搜索运算符；Outlook 使用 $search；Fastmail 和 IMAP 收件箱使用文本搜索。

参数	类型	必需	说明
`inbox_id`	string (uuid)	必需	要搜索的收件箱的 UUID。调用 list_inboxes 以获取可用的收件箱 ID。
`query`	string	必需	搜索查询。对于 Gmail："from:alice@example.com after:2026/01/01"。对于 Outlook：自然语言或 KQL 查询。
`limit`	integer	可选	最大结果数。默认 20，最大 100。
`offset`	integer	可选	分页偏移量。默认 0。
`include_folders`	array	可选	将搜索限定在这些文件夹名称内。默认：搜索所有文件夹。

send_emailsend:email

从已连接的收件箱发送一封新邮件。支持纯文本、可选 HTML 正文、抄送/密送以及文件附件（总计最多 10 MB）。

参数	类型	必需	说明
`inbox_id`	string (uuid)	必需	用于发送的收件箱的 UUID。调用 list_inboxes 以获取可用的收件箱 ID。
`to`	array[string]	必需	收件人电子邮件地址。最多 50 个。
`subject`	string	必需	邮件主题行。最多 998 个字符。
`body`	string	必需	纯文本邮件正文。
`cc`	array[string]	可选	抄送收件人。默认 []。
`bcc`	array[string]	可选	密送收件人。默认 []。
`html_body`	string	可选	正文的 HTML 版本（multipart/alternative）。调用方负责确保 HTML 安全。
`reply_to`	string	可选	Reply-To 头地址。
`attachments`	array	可选	文件附件。每一项：{ filename, mime_type, data (base64) }。最多 20 项，总计 10 MB。

reply_to_emailsend:email

对一封现有邮件发送回复。会话头（In-Reply-To、References）会自动设置。支持全部回复和附件。

参数	类型	必需	说明
`inbox_id`	string (uuid)	必需	包含原始邮件的收件箱的 UUID。调用 list_inboxes 以获取可用的收件箱 ID。
`message_id`	string	必需	被回复邮件的服务商邮件 ID。
`body`	string	必需	纯文本回复正文。
`html_body`	string	可选	可选的回复 HTML 版本。
`reply_all`	boolean	可选	回复全部原始收件人（To + Cc）。默认 false。
`attachments`	array	可选	文件附件。与 send_email 模式相同。最多 20 项。

错误代码

错误代码与重试指南。

认证、权限范围和速率限制失败会返回一个带有数字代码的 JSON-RPC error 对象。工具执行失败（收件箱未找到、服务商错误等）会返回一个正常的 result，其中 isError: true，并在 content[0].text 中提供人类可读的消息。

代码	类型	发生时机	可重试
`-32001`	JSON-RPC error	API 密钥缺失、格式错误、已撤销或已过期。当 API 密钥缺少所调用工具所需的权限范围时也会返回。	否
`-32601`	JSON-RPC error	未知的 JSON-RPC 方法（例如调用 initialize、tools/list、tools/call 以外的方法）	否
`-32602`	JSON-RPC error	未知的工具名称，或 tools/call 中缺少 / 无效的参数	否
`-32029`	JSON-RPC error	超出每密钥速率限制或套餐每日配额。检查 data.error_code："rate_limit_exceeded" 还是 "quota_exceeded"。重试前检查 data.retry_after（秒）。
`isError: true`	Tool result	工具已执行但遇到错误（收件箱未找到、邮件未找到、服务商认证失败、收件人无效、附件过大、服务商 5xx）。错误描述在 content[0].text 中。	否

执行错误响应示例

json

// Tool execution error: inbox not found
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{ "type": "text", "text": "Inbox not found or not accessible." }],
    "isError": true
  }
}

// Rate limit error: JSON-RPC error object with data
{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32029,
    "message": "Rate limit exceeded",
    "data": {
      "error_code": "rate_limit_exceeded",
      "window": "per_minute",
      "limit": 100,
      "used": 100,
      "retry_after": 34
    }
  }
}

速率限制

速率限制与配额。

每密钥滚动窗口

100 次/分钟 · 1,000 次/小时 · 10,000 次/天

无论套餐如何，均按每个 API 密钥强制执行。超出时，服务器返回错误代码 -32029，并附带 data.error_code: "rate_limit_exceeded" 和一个 data.retry_after 字段（秒）。重试前请遵守该值。

套餐每分钟上限

免费 60 次/分钟 · Solo 300 次/分钟 · Team 1,000 次/分钟

用量是无限量的；这是一个每工作区的合理使用突发限制（在你所有 API 密钥间汇总）。超出时，调用会返回 data.error_code: "rate_limit_exceeded"，并附带 data.window: "per_minute" 和一个 data.retry_after 倒计时（秒）。升级你的套餐可获得更高的上限。

安全重试

始终遵守 retry_after；切勿盲目重试发送

对于 rate_limit_exceeded 错误，请在重试前等待 data.retry_after 秒。对于 provider_error 请使用指数退避。请勿在 provider_error 时自动重试 send_email，因为该邮件可能已被服务商接受。

准备好连接你的收件箱了吗？

从免费套餐开始：无限量，无需信用卡。升级到 Solo 或 Team 可获得更高的突发限额和团队功能。

免费开始使用查看价格

四步即可让你的智能体拥有一个收件箱。