mcp-hey 是一个本地运行的 Model Context Protocol（MCP）服务器，为 Claude 及任何兼容 MCP 的客户端提供对 Hey.com 邮箱的读写访问。其底层并非官方公开 API，而是对 Hey.com 网页接口的逆向工程封装，配合与浏览器一致的 HTTP 请求头与 TLS 特征以降低被识别风险。项目完全在本地运行，不依赖云端中转，也不存储账号凭据，仅将会话 Cookie 保存在磁盘上。
mcp-hey 包含两个部件：一个用 Bun/TypeScript 编写的 MCP 服务器，通过 stdio 暴露 Hey 相关工具；一个 Python 辅助脚本，在登录时借助系统 webview 捕获会话 Cookie。
主要能力包括：读取 Imbox、Feed、Paper Trail、Set Aside、Reply Later、Drafts、Trash 和 Spam 等分类下的邮件；下载附件并解析邮件中的日历邀请；发送与回复邮件线程；跨收件箱搜索邮件；整理邮件（搁置、稍后回复、筛选进/出、置顶等）。服务器使用本地 SQLite 缓存以加速重复读取并提供全文搜索，空闲内存约 30 MB。
使用方式：需要 Bun 1.1+、Python 3.10+（如需按 CLAUDE.md 的 Python 工具链操作还需 UV）以及一个 Hey.com 账号。开发与测试环境为 macOS 和 Linux，Windows 用户可能需要 WSL。安装时克隆仓库后执行 bun install 与 uv pip install -r auth/requirements.txt。首次运行 bun run dev 会打开系统 webview 的 Hey.com 登录页，登录后辅助脚本将会话 Cookie 写入 data/hey-cookies.json（权限 600）并退出；之后 MCP 客户端会自行启动服务器实例，直到会话过期。随后需在 MCP 客户端（Claude Code、Claude Desktop、Cursor 等）中配置启动命令，通常为 bun run src/index.ts，macOS 图形应用中可能需要使用 bun 的绝对路径。项目还提供 Dockerfile，但容器内不包含 Python 认证辅助与 webview 登录，需通过挂载卷提供已有的会话 Cookie。启动时服务器会校验 Cookie 文件，缺失或过期则尝试拉起认证脚本；工具调用直接请求 Hey.com，解析 HTML 并缓存到 SQLite；写操作前会获取新的 CSRF 令牌。共提供 34 个工具，详见 docs/TOOLS.md。
隐私与安全方面：不存储密码或凭据，仅写入权限为 600 的会话 Cookie；认证完全在 Hey 自有登录页内完成；所有数据留在本机，项目不发送遥测；MCP 使用 stdio 传输，服务器不开放网络监听；会话有效性在启动时和敏感操作前检查。
限制与风险：使用非官方 API，Hey.com 前端变化可能导致功能失效，需关注 docs/API.md；仅支持轮询，没有实时通知；暂不支持附件上传；每个 MCP 服务器实例仅支持单个账号；异常访问模式理论上可能触发 Hey 的反滥用机制，服务器虽遵循 x-ratelimit 头并指数退避但不保证；仅支持英文界面，服务器解析英文 HTML 字符串（如“You ignored this thread”、标签名、按钮文本），非英文区域设置下无法正常工作；与许多 MCP 服务器一样存在提示注入风险（致命三要素），恶意邮件可能试图指令 Claude 泄露其他消息，应在批准敏感操作前进行审查。
常见问题：认证 webview 未打开时需确认 Python 3.10+ 与依赖安装、Linux 下 webview 后端可用；401/403 表示会话过期，删除 data/hey-cookies.json 后重新运行 bun run dev；429 为速率限制，客户端会自动退避，持续出现时减少并发或稍等；MCP 客户端无法启动服务器时，args 需使用绝对路径，bun 报 spawn bun ENOENT 需参考 macOS 下 bun PATH 的解决办法；Cookie 名称变更（如 _hey_session 改为 session_token）可能导致认证静默失败，需重新捕获 Cookie 并对照文档。
项目以 MIT 许可证发布，欢迎通过 PR 贡献，建议使用约定式提交、推送前运行 bun run format 与 bun run lint、确保 bun test 通过，并在发现或修改 Hey.com API 行为时更新 docs/API.md。
