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、Drafts、Trash 和 Spam 的电子邮件

• 下载附件并解析电子邮件中的日历邀请

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

• 跨邮箱搜索电子邮件

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

• 本地 SQLite 缓存，可实现更快的重复读取和全文搜索

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

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

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

Related MCP server: email-mcp

设置

先决条件

• 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
   uv pip install -r auth/requirements.txt

3. 首次运行 — 身份验证

   bun run dev

   1. 系统 Webview 将打开 Hey.com 的登录页面。正常登录。

   2. 辅助程序将会话 Cookie 捕获到 data/hey-cookies.json（权限 600）并退出。

   3. 按 Ctrl+C — 您的 MCP 客户端将从现在开始启动自己的服务器实例。

   4. 后续运行将重复使用存储的会话，直到其过期。

MCP 客户端配置

以下所有客户端都使用相同的 command/args 格式。在 macOS 上，您几乎肯定需要 bun 的绝对路径 — 请参阅下方的 macOS: bun PATH。

Claude Code

最快的方法是使用 CLI：

claude mcp add --transport stdio hey --scope user -- bun run /absolute/path/to/mcp-hey/src/index.ts

服务器在当前会话中立即可用。

或者，将其添加到项目根目录的 .mcp.json（或用户范围服务器的 ~/.claude.json）中：

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

如果您直接编辑该文件，请重启 Claude Code 会话以使其生效。

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。

Docker

包含一个用于容器化部署和 Glama 兼容性的 Dockerfile。

构建镜像：

docker build -t mcp-hey .

冒烟测试服务器（应返回列出可用工具的 JSON-RPC 响应）：

printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' | docker run -i mcp-hey

注意： Docker 镜像仅运行 MCP 服务器。Python 身份验证辅助程序和 Webview 登录在容器内不可用。您必须通过卷挂载将预先存在的会话 Cookie 提供给 data/hey-cookies.json 以进行身份验证操作。

macOS: bun PATH

GUI 应用程序（Claude Desktop、Cursor）和由 Claude Code 启动的 Shell 并不总是从您的交互式终端继承 PATH，因此通过 Homebrew 安装的 bun 可能会因 spawn bun ENOENT 而失败，或者根本无法连接。通过在 command 中使用 bun 的绝对路径来修复：

• Apple Silicon Homebrew — /opt/homebrew/bin/bun

• Intel Homebrew — /usr/local/bin/bun

• 手动安装 — 在终端中运行 which bun 以找到它

示例：

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

架构

数据流

1. MCP 客户端（Claude Code、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
      attachments.ts   # Download attachments, parse calendar invites
    __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 (33 tools)
    hey-features-doc.md  # Hey.com feature mapping

可用工具

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

隐私与安全

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

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

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

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

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

请参阅 SECURITY.md 了解如何报告漏洞。

限制

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

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

• 无实时通知：仅轮询。

• 尚不支持附件上传。

• 每个 MCP 服务器实例仅限一个账户。

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

• 仅限英语 UI：服务器解析 Hey.com 的 HTML 响应并匹配英语字符串（例如“You ignored this thread”、标签名称、按钮文本）。如果 Hey.com 设置为非英语语言环境，它将无法正常工作。

故障排除

• 身份验证 Webview 未打开 — 确认 Python 3.10+ 在 PATH 中，并且 uv 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 错误，请减少并发工具的使用或等待几分钟。

• MCP 客户端无法启动服务器 — args 必须是绝对路径，而不是相对路径。如果 bun 本身因 spawn bun ENOENT 而失败，请参阅 macOS: bun PATH。

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

贡献

欢迎通过 Pull Request 贡献。请：

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

• 在推送前运行 bun run format 和 bun run lint（由 Biome 提供支持）。

• 确保 bun test 通过。

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

请参阅 CLAUDE.md 了解完整的开发工作流程。

许可证

MIT 许可证 — 请参阅 LICENCE。