Pidgeon

@pidgeon-ai/mcp

一个 MCP 服务，为你的 AI Agent 提供专属电子邮箱。Pidgeon 是面向 AI Agent 的电子邮箱 API。它为 Agent 提供专属邮箱，让它们像人一样处理电子邮件。

通过 Model Context Protocol，Agent 可以创建邮箱地址、发送邮件、等待回复并提取其中的验证码、在邮件会话中回复，以及将对话交给他人处理。有两种接入方式，它们使用的是同一个服务。

托管版：提供 URL，登录即可

claude mcp add --transport http pidgeon https://pidgeon.ai/api/mcp

首次调用会返回 401，客户端会将你引导至 Pidgeon，通过 OAuth 登录。你可以选择它的权限范围——只读、读取和发送，或完全访问——以及它可访问的邮箱地址。Claude 的自定义连接器、ChatGPT、Cursor、Codex 和 VS Code 使用同一个 URL，并以相同方式登录。无需安装。

如果没有人在场为 Agent 登录，可以改用密钥：

claude mcp add --transport http pidgeon https://pidgeon.ai/api/mcp \
  --header "Authorization: Bearer $PIDGEON_API_KEY"

Claude Code、Codex、Cursor 和 Gemini CLI 插件会安装托管服务，并附带一项教 Agent 如何使用它的技能： pidgeon-ai/pidgeon-plugins。

或者安装此软件包

适用于以本地进程运行 MCP 服务的客户端。

PIDGEON_API_KEY=pgn_live_… npx -y @pidgeon-ai/mcp init

此命令会使用 API 验证密钥，并告知它可访问哪些邮箱地址——这是一个 JSON 代码块无法回答的问题；否则，你只会发现模型悄悄报错，而你却无从得知。随后，它会在当前目录写入 .mcp.json，并打印写入的内容。

使用 --print 可查看配置而不写入文件；如果你的客户端将配置保存在其他位置，这正是你需要的选项。使用 --force 可替换已有配置项。

密钥通过环境变量引用，而不会写入文件，因此配置可以提交，而凭据不会泄露：

{
  "mcpServers": {
    "pidgeon": {
      "command": "npx",
      "args": ["-y", "@pidgeon-ai/mcp"],
      "env": { "PIDGEON_API_KEY": "${PIDGEON_API_KEY}" }
    }
  }
}

pgn_live_… 密钥可从 pidgeon.ai/app/developers/keys 获取。还没有账户？Agent 可以通过阅读 pidgeon.ai/skill.md 自行注册；它唯一需要人提供的是一个六位数验证码。

PIDGEON_BASE_URL 可将其指向其他位置，这样你就可以在本地检出版本上运行它。

文档：pidgeon.ai/docs/mcp。

工具

工具	功能说明
list_addresses	此凭证可以访问的地址。
create_address	创建一个供 Agent 使用的地址。
get_address	按 ID 获取一个地址。
list_threads	某个地址中的对话，按时间从新到旧排列。
get_thread	按 ID 获取一个对话。
list_messages	某个对话中的消息，按时间从旧到新排列——这是回复前要阅读的文本。
search_messages	在此凭证可以访问的所有地址中进行全文搜索，并按相关性排序。
send_message	使用此凭证获准发送邮件的地址进行发送。
get_message	按 ID 获取一条消息，包括正文、我们保留的标头，以及发件域名记录所证明的内容——authentication.spf、.dkim、.dmarc；值为 null 表示未报告，而非验证失败。
await_message	等待某个地址收到消息——例如，提交注册表单后——并返回消息及 extracted.codes 和 extracted.links：验证码和确认链接，最可能的结果排在最前。
reply_to_message	收件人、主题和线程会从要回复的消息中读取，因此你只需提供正文。
create_draft	撰写消息但不发送，供人工阅读和发送——当有人要求你准备回复以供审批时使用。
read_attachment	读取一个附件的文本内容，例如 CSV、日志、JSON 或日历文件。
update_thread	更新对话的负责人及其当前进度。
update_message	为消息加星标，或将其移至 archive、spam 或 trash。
list_send_rules	获取某个地址的允许列表和阻止列表，以及关联的发送策略。
list_receive_rules	获取决定哪些内容可到达某个地址的规则——按发件人或域名拒收、标记为垃圾邮件、移至废纸篓、归档或放入收件箱。
list_folders	获取某个地址的所有文件夹及其计数。
list_folder	获取某个地址的一个文件夹，按时间从新到旧排列，每行一个对话——list_threads 显示有哪些对话，而此工具显示它们归档的位置及列表中的样子。
list_changes	获取自 sync_cursor 以来某个邮箱中的所有变更，包括新收到的邮件，这样长期运行的 Agent 无需重新读取文件夹也能找到一条新消息。
list_events	获取此凭证可以访问的所有邮箱中的每个事件——邮件已接收、已发送、已投递、退信或归档。
list_labels	标签属于地址，而非工作区，因此三个地址上同名的标签实际上是三个不同的标签，各自拥有不同的 ID。
create_label	在某个地址上创建一个标签。
apply_label	标签必须属于对话所在的同一地址——调用该地址的 list_labels 可获取正确的 ID。
remove_label	从一个对话中移除一个标签。
list_pods	Pod 是用于隔离某个客户的容器：它包含地址和域名，从中发送的邮件会建立独立的发件信誉，因此一个客户不会损害另一个客户的邮件送达率。
create_pod	为某个客户创建一个拥有独立发件信誉的容器。
get_metrics	获取一段 days 时间内的已发送、已投递、退信、拒收、投诉、已接收和垃圾邮件数量——根据事件日志统计，因此也包含服务提供商事后报告的结果。

将对话交给人工处理

get_message、reply_to_message、update_message 和 update_thread 构成了 这个循环：读取消息、回复消息、归档消息，并说明由谁负责。

update_thread  id=<thread_id>  owner_type=human

消息会出现在 Web 收件箱中，而 thread.updated 会告知此前负责处理该对话的任何一方， 现在已不再负责。owner_type=agent 会将对话交回给 Agent， status 表示对话所在的队列，assignee_id 指明负责处理的人员。

重试发送只会发送一次

send_message 和 reply_to_message 接受 idempotency_key。重试同一次发送时重复使用这个键， 只会发送一次；重试会在提示未再次发送任何内容后，返回首次发送的结果。如果没有键，在同一 时钟小时内使用相同参数和相同凭据进行的相同调用会被视为重试。若要在该小时内有意 发送两次相同内容，请传入一个新键。

两项值得了解的设置

通常应将 Agent 的地址创建为 reply_only：它可以回复任何曾给它发过消息的人， 但不能主动发起对话。这是结构性限制，而非数量限制。create_address 会接受此设置。

还可以为地址设置结束日期。每张工单或每张发票对应一个地址，在事项结束后便会停止接收邮件； 地址到期后会暂停，但通信记录会保留。

凭据构成全部访问控制

这会向模型提供一个凭据。此软件包不决定可以访问什么——访问范围完全由密钥自身的权限上限 和获准访问的地址决定，并且与其他调用方一样，全部在服务器端控制。

因此，请提供 Agent 所需的权限范围最小的密钥。使用 read 权限创建的密钥永远无法发送消息， 无论它获准访问多少邮箱；只需进行分类处理的 Agent 就应该使用这类密钥。

这不是什么

它只是现有 API 上的协议适配器，仅此而已。没有业务逻辑、数据库、模型或状态。

每个工具都是一个端点：分发器根据每个工具声明的端点运行，而不是根据工具名称运行， 因此无法添加 API 本身不具备的行为；测试也会断言每个端点都存在于已发布的 OpenAPI 文档中。如果这里缺少某项功能，那么 API 中也缺少该功能，应当在 API 中实现。

贡献

此软件包从 pidgeon-ai/pidgeon-js 发布。该仓库会在每次发布时 从 Pidgeon 的主仓库复制，因此无法按原样合并提交到该仓库的拉取请求。 提交问题，说明哪里有问题，或者发送邮件至 [email protected]。

采用 MIT 许可证。