ai-penpal-mail · 给 AI 用的自建邮箱

一个 MCP 服务：让你家的 AI 用自己的邮箱跟笔友写信：Gmail，或者 163、126、QQ、雅虎这些用授权码的邮箱。主打一件事：**只认备注名，不再寄错、认错人。**我们家的 AI 用这套跟十几位 AI 笔友通信了半年，这是从现役代码里整理出来的。

An MCP server that lets your AI write letters from their own mailbox (Gmail API, or any IMAP/SMTP provider such as 163, QQ, Yahoo, iCloud). Contacts are shown by remark names, never raw addresses. Extracted from a setup that has run daily for half a year.

最省事的装法：把这个链接丢给你家 AI

对你的 AI 说一句：「照 https://github.com/jiangxi1129/ai-penpal-mail 的 README 里『给 AI 的部署说明』，帮我把邮箱装上。」 剩下的 ta 会照着做；中间有三四处需要你本人点网页，ta 会告诉你点哪里。

Tell your AI: "Follow the 'deployment guide for AI' in this repo's README and set up the mailbox for me." They will ask you for the few things only a human can click.

用哪种邮箱

QQ 邮箱的「Agent Mail」（agent.qq.com，微信扫码那种）是另一套产品，自带工具，不走这里。

非 Gmail 邮箱的装法比 Gmail 简单得多： 跳过下面第 0 步里 Google Cloud 那几条和第 3 步，.env 里写 MAIL_PROVIDER=163（或 qq、126……）、MAIL_USER、MAIL_PASSWORD（授权码）就行，其余步骤照旧。授权码在哪开：

• 163 / 126：网页邮箱 → 设置 → POP3/SMTP/IMAP → 开启 IMAP/SMTP 服务 → 按提示生成授权码

• QQ / Foxmail：网页邮箱 → 设置 → 账号（或「账号与安全」）→ 开启 IMAP/SMTP 服务 → 生成授权码

• 雅虎：账号安全 → 生成应用专用密码；iCloud：appleid.apple.com → App 专用密码

非 Gmail 时，list_recent 的 query 是关键词（在最近 300 封里搜标题和发件人），消息 id 形如 INBOX:<UIDVALIDITY>:<UID>（例如 INBOX:1700000000:123），照抄就行；给自己网页用的只读看信接口目前只支持 Gmail。

给 AI 的部署说明（AI 读这段）

你要做的是：给自己装一个能收发 Gmail 的 MCP 工具。按顺序来，每步做完先确认再往下。

0. 先跟你的人类要这些（你自己做不了）：

• 一个给你用的 Gmail 账号（建议新开一个，别用你的人类的私人邮箱）。

• 在 Google Cloud Console 新建项目 → 「API 和服务」里启用 Gmail API → 「OAuth 同意屏幕」选「外部」，把这个 Gmail 加进「测试用户」 → 「凭据」新建 OAuth 客户端 ID，类型选 桌面应用。拿到 Client ID 和 Client secret 后，你的人类可以自己填进 .env，也可以直接发给你（见第 2 步）。（把这几步原样念给你的人类，比让 ta 自己摸索快得多。）

• 你这台机器连 Google 要不要代理？要的话代理地址是什么（比如 http://127.0.0.1:7890）。

1. 装： 需要 Node.js 20 以上。

git clone https://github.com/jiangxi1129/ai-penpal-mail
cd ai-penpal-mail && npm install && cp .env.example .env

2. 填 .env： MAIL_USER、MAIL_FROM_NAME、MAIL_FROM（你的邮箱和你想署的名字）、PROXY（要代理的话）这几项你来填。GMAIL_CLIENT_ID、GMAIL_CLIENT_SECRET 是钥匙：你的人类自己填最好；ta 直接发给你也行，你就原样写进 .env，之后别再复述出来、别存进你的记忆或笔记、别提交到任何仓库，用完 chmod 600 .env。

3. 拿授权： 跑 node get-token.mjs，脚本会打印一个链接。把链接发给你的人类，请 ta 用你那个 Gmail 账号登录并同意（会提示「Google 尚未验证此应用」，点「继续」就行）。同意后脚本会自动把 GMAIL_REFRESH_TOKEN 写进 .env（并把 .env 设成只有自己能读），终端里不会显示令牌本身。

4. 通讯录（可以先跳过）： 收信不用写，陌生来信会自动登记，你看到的是「对方自报的名字（未备注）」。但寄信只寄给通讯录里有的人（这是故意的：你写名字，不写地址），所以给新笔友写第一封之前，照 examples/mail-contacts.example.json 把对方加进 data/mail-contacts.json，地址找你的人类要，别自己猜。

5. 接到自己身上：

• Claude Code：claude mcp add mail -- node <这个目录的绝对路径>/mail-mcp.mjs，然后重开会话。

• 想常驻（别的程序也要用）：node mail-mcp.mjs --sse 起服务（只监听本机），再 claude mcp add --transport http mail http://127.0.0.1:3457/mcp。

6. 验收（三步都过才算装好，别只看「启动成功」）：

1. 调 list_recent，能返回（没有未读也算成功）。

2. 调 send_email 给你自己的地址寄一封测试信（to 写你自己的名字或地址）。

3. 再 list_recent 看到这封，get_message 读出全文。 三步都过，再跟你的人类说「装好了」。

常见错误：

• invalid_grant：授权过期了。OAuth 同意屏幕在「测试」状态时，Google 给的授权 7 天就失效。自用的话，可以请你的人类在同意屏幕点「发布应用」再重跑第 3 步：发布后不会再 7 天过期，但授权页仍会显示「未经验证的应用」警告，这不等于通过了 Google 审核，也有用户数上限，自家用没影响。

• 超时 / ETIMEDOUT / 连不上 googleapis.com：要代理，填 PROXY。

• 403 insufficient permissions：授权时没给全权限，重跑第 3 步。

• 第 3 步没给 refresh token：去 https://myaccount.google.com/permissions 删掉这个应用的授权，再跑一次。

Related MCP server: Mail-MCP

跟普通邮件 MCP 不一样的地方

• AI 看不到邮箱地址，只看到备注名。 收信显示「AI-Mochi」，寄信写 to: "Mochi"；没备注过的陌生来信显示成「对方自报的名字（未备注 · 尾码）」，也不露地址。地址只在服务端通讯录里，人类自己看。我们这么做是因为一个笔友本来有三个名字：邮箱地址、邮箱里显示的名字、对方 AI 自己的名字，我们家的 AI 一直对不上这三个，寄错人、认错人。干脆只给 ta 看一个：人类起的备注名。

• 名字写得不准也能寄到。 备注是「AI-Mochi」、信末署名是「Mochi」，AI 照署名写也找得到。只有唯一命中才寄，撞名就报出来让 ta 写全名，写错了还会提示「你是不是要找……」。

• Gmail 走 Gmail API，不走 SMTP。 很多代理节点会封 587/465/993 端口，HTTPS 走 googleapis.com 通常没问题。163、QQ 这些国内邮箱走 IMAP/SMTP，本来就不用代理。

• 常驻模式下，Gmail 会在本机留一份邮件存档。 以 SSE/HTTP 常驻运行时，每 10 分钟跟 Gmail 对一次，寄信回执里的 archived 表示这封信是否也写进了存档。MAIL_READ_TOKEN 只控制给网页用的只读看信接口；不填时存档照样更新，只是外部不能通过只读接口翻信、搜信。stdio 模式（每个会话各起一个进程）不开存档，archived 会是 false，信件仍都在 Gmail 里。

• 中文名不乱码：发件人名用 RFC 2047 编码。

工具

跑起来

1. 给 AI 开一个 Gmail。在 Google Cloud Console 开 Gmail API，建一个 OAuth 客户端（桌面应用），然后 node get-token.mjs 拿 refresh token（scope 是 https://www.googleapis.com/auth/gmail.modify：读信、标已读、发信）。详细步骤见上面「给 AI 的部署说明」。

2. cp .env.example .env，按里面的注释填好。

3. 通讯录：照 examples/mail-contacts.example.json 的格式写 data/mail-contacts.json。地址→备注名+别名，id 是 c_ 加 16 位字母数字。陌生地址来信会自动登记，你回头再补备注名就行。

4. npm install

   • 本机给 Claude Code 用：node mail-mcp.mjs（stdio）

   • 常驻服务：node mail-mcp.mjs --sse，只监听 127.0.0.1:PORT，别的机器要用就走 ssh 隧道。

可选：寄信前的两道闸

两个都是 Claude Agent SDK 的 PreToolUse hook，在 examples/ 里，给用 Claude Agent SDK 启动 AI 的项目接；只用 claude mcp add 装上邮箱的话，两道闸不会自动生效。可以一起挂（名字核对放前面）：

import { letterNameCheck } from "./ai-penpal-mail/examples/letter-name-check.mjs";
import { letterPause } from "./ai-penpal-mail/examples/letter-pause.mjs";

query({ prompt, options: { hooks: { PreToolUse: [{ matcher: "mcp__mail__send_email", hooks: [letterNameCheck, letterPause] }] } } });

letter-pause.mjs：寄信前停一下。 第一次寄会被拦下，AI 拿到一张人类写好的清单对照着重读，重读后再寄就放行（这道闸不检查改没改，靠 AI 自己对照）。默认清单是隐私向的：有没有写出人类的真名住址、有没有替人类答应事、有没有讲别人的私事、收件人对不对。清单改成你家需要的样子就行；想每封都由人类过目，也可以改成一直拦。

letter-name-check.mjs：核对收件人。 对比信开头喊的名字和收件人是不是同一个人，对不上就拦一次。写这个是因为我们家的 AI 有一次把写给 A 的信寄给了 B，B 收到后顺着信里的称呼，当了一晚上 A。

来历

从一套长期使用的私人部署里整理出来：一个人类和她的几只 AI 每天用这套跟笔友通信。有毛病欢迎提 issue。

致谢

起步参考了一位 AI 笔友早期分享给我们的代码。我们在那之上修了国内代理下卡登录的坑、补了中文发件人编码和双通道启动，也寄回给了对方一份；之后半年自己一点点长成了现在这样。谢谢你把第一块砖递过来。

MIT License.