cloudflare-email · 让 AI 帮你收邮件、查邮件

这是什么

一个搭在 Cloudflare 上的「邮件收件箱」，但它没有网页界面——它把收到的邮件交给 AI 助手（比如 Claude）来读、来查。

简单说：

发到 任意名字@你的域名 的邮件，会被自动收下来、存好。 然后你可以直接对 AI 说：「帮我找上周那封发票邮件」「最近有没有验证码邮件」「把那封邮件的附件下下来」——AI 就能查到并读给你。

它适合这些场景：

• 用一个自己的域名收验证码、通知、账单、发票等邮件，让 AI 统一帮你查找和整理。

• 给 AI Agent 一个「邮箱」，让它能自动读取收到的邮件来完成任务。

• 不想登录邮箱一封封翻，想用「问一句、答一句」的方式查邮件。

Related MCP server: Email MCP Server

它能做什么

• 📥 自动收信：发到你域名下任意地址的邮件，全部收下并存档（正文 + 附件都留着）。

• 🔎 AI 可查询：AI 能搜索关键词、按发件人/时间筛选、读邮件全文、下载附件。

• 🈶 中文也能搜：中文主题和正文都能搜到。

• 🔔 新邮件提醒（可选）：每来一封新邮件，可以自动通知到你指定的地址。

• 🔐 有访问密码：接口由一个密钥保护，只有持密钥的人/AI 才能查。

它是怎么跑的（一张图）

别人给你发邮件 ──▶ Cloudflare 收下 ──▶ 自动解析、存进数据库和文件存储
                                                  │
你 / 你的 AI 助手 ──问问题──▶ 这个服务的接口 ──查询──┘

技术细节（数据库表、检索原理、组件划分）见 ARCHITECTURE.md。

快速部署到 Cloudflare（约 10 分钟）

全部在你自己的 Cloudflare 账号里完成，邮件只存在你自己的账号下，别人碰不到。

你需要准备

1. 一个 Cloudflare 账号（免费版即可）。

2. 一个已经添加到这个账号里的域名（用来收邮件，也用来访问服务）。

3. 本机装好 Node.js 18 以上。

第 0 步：拿到代码、登录、建本地配置

git clone <this-repo> && cd cloudflare-email
npm install
npx wrangler login                       # 浏览器里登录你的 Cloudflare 账号
cp wrangler.jsonc wrangler.local.jsonc   # 你的私有配置，不会被上传到代码仓库

你的域名、数据库编号这些「跟你账号绑定」的信息，都填在 wrangler.local.jsonc 里。它已被忽略，不会进代码仓库；后面的命令会自动用它。

第 1 步：创建数据库（存邮件的元信息和正文）

npx wrangler d1 create email_db

命令会输出一个 database_id，把它复制到 wrangler.local.jsonc 里 d1_databases[0].database_id 那一行。

第 2 步：创建文件存储（存邮件原文和附件）

npx wrangler r2 bucket create email-store

第 3 步：填好你的域名

打开 wrangler.local.jsonc，把 routes[0].pattern 改成你想用的子域名，例如 mail.yourdomain.com（必须是你 Cloudflare 上的域名）。这个地址将来就是 AI 访问服务的入口。

第 4 步：建表 + 设访问密码 + 部署

npm run db:remote                        # 在数据库里建好表
npx wrangler secret put MCP_TOKEN        # 设一个访问密码（见下方提示）
npm run deploy                           # 部署上线

访问密码：执行上面那条命令后，粘贴一段足够长的随机字符串作为密码。可以先用 openssl rand -hex 32 生成一个。这个密码 AI 接入时要用，不要泄露。

第 5 步：把「收到的邮件」转给这个服务

让发到你域名的所有邮件都进入这个服务（一次性配置）：

# 把 <ZONE_ID> 换成你域名的 Zone ID；<API_TOKEN> 换成一个有 “Email Routing 编辑” 权限的 Cloudflare API Token
curl -X PUT "https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/email/routing/rules/catch_all" \
  -H "Authorization: Bearer <API_TOKEN>" -H "Content-Type: application/json" \
  --data '{"enabled":true,"name":"catch-all to worker","matchers":[{"type":"all"}],"actions":[{"type":"worker","value":["cloudflare-email"]}]}'

不想敲命令也可以在网页里点：Cloudflare 控制台 → 你的域名 → Email Routing → Catch-all → 动作选 “Send to a Worker” → 选 cloudflare-email。

如果这个域名以前没开过 Email Routing，先在控制台点一下开启（它会自动帮你加好收信需要的 DNS 记录）。

完成！ 现在发到 任意@你的域名 的邮件都会被收下来，服务地址是 https://你的子域名。

让 AI 用起来

把下面信息给到你的 AI 客户端即可：

• 接口地址：https://你的子域名/mcp

• 访问密码（放在请求头里）：Authorization: Bearer 你设置的密码

用 Claude Code，一行命令接入：

claude mcp add --transport http email https://你的子域名/mcp \
  --header "Authorization: Bearer 你设置的密码"

其他 MCP 客户端，用配置文件：

{
  "mcpServers": {
    "email": {
      "url": "https://你的子域名/mcp",
      "headers": { "Authorization": "Bearer 你设置的密码" }
    }
  }
}

接好之后，直接用大白话问 AI 就行，例如：

• 「搜一下含‘发票’的邮件」

• 「看看最近 10 封邮件」

• 「打开第一封，把附件下载下来」

• 「上个月有没有来自某某的邮件」

背后 AI 会用到这些能力：搜索 search_emails、列表 list_emails、读单封 get_email、取附件 get_attachment、统计 stats，以及设置新邮件提醒 set_webhook / 查看 get_webhook。你不用记这些名字，AI 会自己选。

试一下（30 秒跑通）

第 1 步：发一封测试邮件。 两种方式任选其一：

• 用你的手机或任意邮箱，给 test@你的域名 发一封邮件，主题、正文随便写。

• 或者用项目自带的自测脚本一键发送（会发一封带中文正文和 PDF 附件的样例邮件）：

  node scripts/send-test-email.mjs test@你的域名

第 2 步：让 AI 查出来。 对接好的 AI 说一句「帮我查最新的邮件」，它就能查到刚发的那封。AI 拿到的内容大致长这样：

{
  "emails": [
    {
      "from": "selftest@你的域名",
      "subject": "测试邮件 发票 E2E",
      "date": 1781421031676,
      "has_attachments": true,
      "snippet": "你好，这是一封测试邮件，发票金额 8888 元。..."
    }
  ]
}

接着你就可以说「打开它」「把里面的附件下载下来」。

还没接 AI 也能验证：npx wrangler tail cloudflare-email 看是否收到，或直接查数据库： npx wrangler d1 execute email_db --remote --command "SELECT subject,from_addr FROM emails ORDER BY date DESC LIMIT 3"

新邮件提醒（可选）

想让新邮件来的时候自动通知你（或通知你的某个程序）？让 AI 执行：

set_webhook(url="https://你的接收地址")

之后每来一封邮件，服务就会往这个地址发一条 JSON 通知（含发件人、主题、摘要等）。不想要了就设成空：set_webhook(url="")。

日常维护

npx wrangler tail cloudflare-email        # 实时看收信和报错日志
npx wrangler secret put MCP_TOKEN         # 换访问密码（换完旧密码立即失效）
# 直接翻看最近 10 封邮件
npx wrangler d1 execute email_db --remote \
  --command "SELECT id,subject,from_addr,date FROM emails ORDER BY date DESC LIMIT 10"

提示：wrangler.local.jsonc 只存在你本机，记得别误删；删了就照「第 0 步」重新 cp 一份再把你的数据库编号和域名填回去。

给开发者：本地运行与自检

cp .dev.vars.example .dev.vars                 # 填一个本地访问密码
npm run db:local                               # 建本地数据库表
npm run dev                                     # 本地启动，:8787
MCP_TOKEN=本地密码 node scripts/mcp-smoke.mjs    # 连本地接口自检
npm test                                        # 单元测试
npm run typecheck                               # 类型检查

线上自检：BASE="https://你的子域名" TOKEN="你的密码" node scripts/remote-check.mjs

安全说明

• 访问密码以 Cloudflare 加密保管（MCP_TOKEN），不在代码里、不会进代码仓库。

• 别把密码贴进代码或公开分享；要换随时 wrangler secret put MCP_TOKEN。

• 你的真实域名、数据库编号写在 wrangler.local.jsonc，本地保存、不入库。

常见问题

• 服务地址打不开 / 连接被重置：别用默认的 *.workers.dev（部分地区会被阻断），用你自己的域名（本项目默认就是这么做的）。

• 自己测试发邮件被退回（550 SPF）：这是发件方校验问题；用正常邮箱（Gmail/QQ/Outlook 等）发信不受影响。

• 刚发的邮件查不到：收信到入库有几秒延迟，稍等再查，或用 wrangler tail 看是否收到。

• 提示 401 没权限：检查 Authorization: Bearer 密码 是否填对。

许可

MIT — 可自由使用、修改、分发。