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/403after weeks: the session expired. Deletedata/hey-cookies.jsonand runbun 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.mdchangelog.
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.
