MCP Hey

mcp-hey

A local MCP server that gives Claude read/write access to your Hey.com inbox. A Bun/TypeScript server exposes the tools over stdio, and a small Python helper captures session cookies through the system webview at login. No cloud relay, no stored credentials.

Unofficial API. Hey.com has no public API. mcp-hey uses its web endpoints with browser-identical requests, so things can break without notice. The current surface is in docs/API.md.

Setup

Prerequisites: Bun 1.1+, Python 3.10+ and a Hey.com account. Tested on macOS and Linux; Windows likely needs 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

The helper saves session cookies to data/hey-cookies.json (mode 600). Later runs reuse them until they expire.

MCP client configuration

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

Use absolute paths. GUI apps often lack your shell's PATH, so if you see spawn bun ENOENT, set command to the output of which bun (Homebrew: /opt/homebrew/bin/bun).

Docker: docker build -t mcp-hey ., then printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' | docker run -i mcp-hey. The image has no login helper, so mount existing cookies at data/hey-cookies.json.

Tools

37 tools. Parameters, return shapes and errors are in docs/TOOLS.md.

Sender groups

Every message a tool returns carries sender_group: where Hey delivers new mail from that sender (imbox, feed, paper_trail, screened_out, else unknown), from the "Deliver their emails to…" setting on their contact page. It describes the sender, not the message.

hey_search, hey_list_set_aside, hey_list_reply_later, hey_list_label_emails and hey_list_collection_emails take an optional group, for example group: ["imbox"] to leave out newsletters and receipts. By default (HEY_SENDER_GROUPS=filter) tools tag from the local cache and only a filtered call asks Hey; on looks up a few senders on every call, off removes the field. Details: docs/TOOLS.md.

Architecture

Requests carry browser-realistic headers, write operations fetch a fresh CSRF token first, and the client backs off on x-ratelimit.

Privacy and limitations

• Only session cookies are stored (mode 600); login happens in Hey's own page. No telemetry, no network listener.
• Prompt injection: this server has the lethal trifecta. A malicious email could try to make Claude exfiltrate others, so review risky actions before approving them.
• No calendar event creation, attachment uploads or real-time notifications. One account per instance.
• Hey's HTML is parsed against English UI strings, so a non-English Hey locale will not work.
• Unusual access patterns could trip Hey's anti-abuse systems despite the rate-limit handling.

Report vulnerabilities via SECURITY.md.

Troubleshooting

• Webview does not open: check Python 3.10+ and that python -c "import webview" works (Linux needs a webview backend).
• 401/403 after weeks: the session expired. Delete data/hey-cookies.json and run bun run dev.
• Sustained 429s: reduce concurrent tool use or wait a few minutes.
• Auth silently fails after a Hey update: Hey has renamed session cookies before. See the docs/API.md changelog.

Contributing

Conventional commits; bun run format, bun run lint and bun test must pass; update docs/API.md when Hey's behaviour changes. See CLAUDE.md.

Licence

MIT. See LICENCE.