mcp-hey

一个本地模型上下文协议 (MCP) 服务器，通过逆向工程的 Web API 为 Claude 提供对您的 Hey.com 收件箱的读/写访问权限。

mcp-hey 包含两个部分：一个通过 stdio 公开 Hey 工具的 Bun/TypeScript MCP 服务器，以及一个使用系统 Webview 在登录时捕获会话 Cookie 的小型 Python 辅助程序。所有内容均在本地运行——没有云中继，不存储凭据，仅在磁盘上存储会话 Cookie。

注意 — 非官方 API。 Hey.com 不发布公共 API；mcp-hey 对其 Web 端点进行了逆向工程，并将其与浏览器相同的 HTTP 请求配对。服务可能会在没有通知的情况下中断。当前记录的接口位于 docs/API.md。

功能

• 读取来自 Imbox、Feed、Paper Trail、Set Aside 和 Reply Later 的电子邮件

• 发送和回复电子邮件线程

• 跨邮箱搜索电子邮件

• 整理邮件（搁置、稍后回复、筛选进入/移出、置顶）

• 本地 SQLite 缓存，用于更快的重复读取和全文搜索

• 轻量级 — 空闲内存占用约 30 MB

• 与浏览器相同的标头和 TLS 配置，以避免被检测

• 完全在您的机器上运行；使用 stdio 传输，无网络暴露

设置

先决条件

• Bun 1.1 或更高版本

• Python 3.10 或更高版本（如果您想遵循 CLAUDE.md 中的 Python 工具链，还需要 UV）

• Hey.com 账户

• 平台：在 macOS 和 Linux 上开发和测试。Windows 用户可能需要 WSL — pywebview 的 Windows 后端目前尚未经过测试。

安装

1. 克隆此仓库

   git clone https://github.com/Sealjay/mcp-hey.git
   cd mcp-hey

2. 安装依赖项

   bun install
   pip install -r auth/requirements.txt

3. 首次运行 — 身份验证

   bun run dev

   Python 身份验证辅助程序会打开一个指向 Hey.com 的系统 Webview。像往常一样登录；辅助程序会将会话 Cookie 捕获到 data/hey-cookies.json（权限锁定为 600）并退出。后续运行将重复使用存储的会话，直到其过期。

MCP 客户端配置

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)：

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

重启 Claude Desktop。您应该会看到 hey 被列为可用的集成。

Cursor

添加到 ~/.cursor/mcp.json：

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

重启 Cursor。

架构

数据流

1. MCP 客户端（Claude Desktop / Cursor）通过 stdio 启动 bun run src/index.ts。

2. 启动时，服务器会验证 data/hey-cookies.json。如果缺失或过期，它会启动 auth/hey-auth.py，该程序会在系统 Webview 中打开 Hey 并写入新的 Cookie。

3. 工具调用直接使用浏览器真实的标头访问 Hey.com；响应被解析（HTML 通过 node-html-parser）并缓存在 SQLite 中。

4. 写操作在提交前会获取新的 CSRF 令牌。

项目结构

mcp-hey/
  src/
    index.ts           # MCP server entry point
    hey-client.ts      # HTTP client with cookie injection
    session.ts         # Session management and validation
    errors.ts          # Error classes and sanitisation
    cache/             # SQLite cache (db, schema, messages, search)
    tools/             # MCP tool implementations
      read.ts          # Reading and listing
      send.ts          # Send, reply, forward
      organise.ts      # Triage, labels, bubble up, etc.
      http-helpers.ts  # Shared CSRF retry and endpoint fallback
    __tests__/         # Test suites
  auth/
    hey-auth.py        # Python auth helper (pywebview)
    requirements.txt
  data/
    hey-cookies.json   # Session storage (gitignored, chmod 600)
  docs/
    API.md             # Hey.com API surface documentation
    TOOLS.md           # MCP tool reference (41 tools)

可用工具

41 个按功能分组的工具。有关参数、返回形状和错误行为，请参阅 docs/TOOLS.md。

隐私与安全

• 绝不存储凭据 — 仅存储会话 Cookie，并以 600 权限写入。

• 身份验证完全在 Hey 自己的登录页面（系统 Webview）内进行。

• 所有数据都保留在您的机器上。本项目不发送任何遥测数据。

• MCP 使用 stdio 传输 — 服务器从不打开网络监听器。

• 会话有效性在启动时和敏感操作前进行检查。

有关如何报告漏洞，请参阅 SECURITY.md。

限制

• 提示注入风险：与许多 MCP 服务器一样，此服务器也受到 致命三要素 的影响。到达您收件箱的恶意电子邮件可能会尝试指示 Claude 窃取其他消息。请相应地对待工具界面，并在批准前审查风险操作。

• 非官方 API：Hey.com 的前端可能会在没有通知的情况下更改并导致中断。请预料到偶尔会出现中断，并查看 docs/API.md 以了解已知的差异。

• 无实时通知：仅支持轮询。

• 尚不支持附件上传。

• 每个 MCP 服务器实例仅支持单个账户。

• 账户风险：激进或异常的访问模式理论上可能会触发 Hey 的反滥用系统。服务器会遵守 x-ratelimit 标头并进行指数退避，但无法保证。

故障排除

• 身份验证 Webview 未打开 — 确认 Python 3.10+ 在 PATH 中，并且 pip install -r auth/requirements.txt 已成功执行。在 Linux 上，确保 Webview 后端可用（python -c "import webview" 不应报错）。

• 使用数周后出现 401/403 响应 — 您的 Hey 会话已过期。删除 data/hey-cookies.json 并再次运行 bun run dev 以重新进行身份验证。

• 速率限制 (429) — 客户端会遵守 x-ratelimit 标头并进行退避。如果您看到持续的 429 错误，请减少并发工具的使用或等待几分钟。

• Bun 无法在 Claude Desktop/Cursor 中找到脚本 — args 路径必须是绝对路径，而不是相对路径，并且必须能从客户端的启动环境中找到 bun（在 macOS 上，这可能意味着使用完整路径，例如 /opt/homebrew/bin/bun）。

• Cookie 名称已更改 — Hey 之前曾重命名过会话 Cookie（例如 _hey_session → session_token，请参阅 CLAUDE.md 中的日志）。如果 Hey 更新后身份验证静默失败，请捕获新的 Cookie 并进行比较。

贡献

欢迎通过 Pull Request 贡献代码。请：

• 使用约定式提交 (feat, fix, docs, refactor, test, perf, cicd, revert, WIP)。

• 在推送前运行 bun run format 和 bun run lint。

• 确保 bun test 通过。

• 如果您发现或更改了任何 Hey.com API 行为，请更新 docs/API.md。

有关完整的开发工作流程，请参阅 CLAUDE.md。

许可证

MIT 许可证 — 请参阅 LICENCE。