Mcp Hey

mcp-hey

一个本地 MCP 服务，可让 Claude 读写你的 Hey.com 收件箱。Bun/TypeScript 服务通过 stdio 提供工具，另有一个小型 Python 辅助程序，可在登录时通过系统 WebView 获取会话 Cookie。没有云中转，也不存储凭据。

非官方 API。 Hey.com 没有公开 API。mcp-hey 使用其 Web 端点，并发送与浏览器完全相同的请求，因此相关功能可能随时失效。当前支持的接口见 docs/API.md。

设置

前置条件： Bun 1.1+、Python 3.10+ 和 Hey.com 账户。在 macOS 和 Linux 上测试；Windows 可能需要 WSL。

git clone https://github.com/Sealjay/mcp-hey.git
cd mcp-hey
bun install
uv pip install -r auth/requirements.txt
bun run dev   # first run: log in to Hey in the webview, then Ctrl+C

辅助程序会将会话 Cookie 保存到 data/hey-cookies.json（权限模式 600）。后续运行会重复使用这些 Cookie，直至其过期。

MCP 客户端配置

{
  "mcpServers": {
    "hey": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/mcp-hey/src/index.ts"]
    }
  }
}

客户端	位置
Claude Code	claude mcp add --transport stdio hey --scope user -- bun run /absolute/path/to/mcp-hey/src/index.ts，或在 .mcp.json 中使用上方的代码块
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json
Cursor	~/.cursor/mcp.json

请使用绝对路径。图形界面应用通常无法访问 shell 的 PATH，因此如果看到 spawn bun ENOENT，请将 command 设置为 which bun 的输出（Homebrew：/opt/homebrew/bin/bun）。

**Docker：**运行 docker build -t mcp-hey .，然后运行 printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' | docker run -i mcp-hey。镜像不包含登录辅助程序，因此请将已有 Cookie 挂载到 data/hey-cookies.json。

工具

共 37 个工具。参数、返回格式和错误见 docs/TOOLS.md。

类别	工具
读取	hey_list_emails（imbox、feed、paper_trail、trash、spam、drafts、sent）、hey_imbox_summary、hey_list_set_aside、hey_list_reply_later、hey_list_screener、hey_read_email、hey_download_attachment、hey_get_calendar_invite
标签与集合	hey_list_labels、hey_list_label_emails、hey_label、hey_list_collections、hey_list_collection_emails、hey_collection
发送与草稿	hey_send_email、hey_reply、hey_forward、hey_save_draft、hey_edit_draft、hey_delete_draft
分流	hey_set_aside、hey_unset_aside、hey_reply_later、hey_remove_reply_later、hey_move_to、hey_set_status、hey_mark_unseen、hey_mark_seen、hey_read_status、hey_thread_mute
浮现	hey_bubble_up、hey_bubble_up_if_no_reply、hey_pop_bubble
筛选	hey_screen、hey_screen_by_id
搜索与缓存	hey_search、hey_cache_status

发件人分组

工具返回的每条消息都带有 sender_group：Hey 根据联系人的页面中“将他们的邮件发送到……”设置，将该发件人的新邮件投递到哪里（imbox、feed、paper_trail、screened_out，否则为 unknown）。它描述的是发件人，而不是消息。

hey_search、hey_list_set_aside、hey_list_reply_later、hey_list_label_emails 和 hey_list_collection_emails 可选用 group，例如，设置 group: ["imbox"] 可排除新闻通讯和收据。默认情况下（HEY_SENDER_GROUPS=filter），工具会从本地缓存添加标签，只有带筛选条件的调用才会查询 Hey；on 会在每次调用时查询少数发件人，off 则移除该字段。详情请见：docs/TOOLS.md。

架构

组件	描述
MCP 服务	基于 MCP TypeScript SDK v2 的 Bun/TypeScript。stdio 提供 MCP 2026-07-28 及更早版本的支持；空闲时约占用 30 MB 内存
身份验证助手	Python/pywebview，仅在缺少 Cookie 或 Cookie 过期时启动
缓存	用于存储消息、会话和全文搜索的本地 SQLite

请求会携带符合真实浏览器特征的标头，写入操作前会先获取新的 CSRF 令牌，客户端会针对 x-ratelimit 进行退避。

隐私与限制

• 仅存储会话 Cookie（权限模式为 600）；登录在 Hey 自有页面中进行。无遥测数据，也不监听网络。
• **提示词注入：**此服务具备致命三要素。恶意邮件可能会试图诱使 Claude 外传其他人的信息，因此请在批准高风险操作前仔细检查。
• 不支持创建日历事件、上传附件或实时通知。每个实例仅支持一个账户。
• Hey 的 HTML 会根据英文 UI 字符串进行解析，因此 Hey 使用非英语界面时无法正常工作。
• 尽管已处理速率限制，异常访问模式仍可能触发 Hey 的反滥用系统。

请通过 SECURITY.md 报告漏洞。

故障排除

• **Webview 未打开：**检查 Python 3.10+，并确认 python -c "import webview" 可以正常运行（Linux 需要 Webview 后端）。
• **数周后出现 401/403：**会话已过期。删除 data/hey-cookies.json 并运行 bun run dev。
• **持续出现 429：**减少并发工具调用，或等待几分钟。
• **Hey 更新后身份验证静默失败：**Hey 以前曾更改会话 Cookie 的名称。请参阅 docs/API.md 的变更日志。

贡献

使用 Conventional Commits；bun run format、bun run lint 和 bun test 必须通过；Hey 的行为发生变化时，请更新 docs/API.md。另请参阅 CLAUDE.md。

许可

MIT。请参阅 LICENCE。