Sealjay/mcp-hey

> A local Model Context Protocol (MCP) server that gives Claude read/write access to your Hey.com inbox via reverse-engineered web APIs.
mcp-hey has two moving parts: a Bun/TypeScript MCP server that exposes Hey tools over stdio, and a small Python helper that uses the system webview to capture session cookies at login. Everything runs locally — no cloud relay, no credentials stored, just session cookies on disk.
> **Warning — unofficial API.** Hey.com does not publish a public API; mcp-hey reverse-engineers its web endpoints and pairs them with browser-identical HTTP requests. Things can break without notice. The current documented surface lives in docs/API.md.
Features
- Read emails from Imbox, Feed, Paper Trail, Set Aside, Reply Later, Drafts, Trash, and Spam
- Download attachments and parse calendar invites from emails
- Send and reply to email threads
- Search emails across boxes
- Organise mail (set aside, reply later, screen in/out, bubble up)
- Local SQLite cache for faster repeated reads and full-text search
- Lightweight — around 30 MB idle memory
- Browser-identical headers and TLS posture to avoid detection
- Runs entirely on your machine; stdio transport with no network exposure
Setup
Prerequisites
- Bun 1.1 or later
- Python 3.10 or later (plus UV if you want to follow the Python tooling in CLAUDE.md)
- A Hey.com account
- **Platform**: developed and tested on macOS and Linux. Windows users will likely need WSL — pywebview's Windows backend is not currently exercised.
Installation
1. **Clone this repository**
2. **Install dependencies**
3. **First run — authenticate**
1. A system webview opens with Hey.com's login page. Log in normally.
2. The helper captures session cookies to data/hey-cookies.json (permissions 600) and exits.
3. Press Ctrl+C — your MCP client will launch its own server instance from here on.
4. Subsequent runs reuse the stored session until it expires.
MCP client configuration
All clients below use the same command/args shape. On macOS, you'll almost certainly need the absolute path to bun — see macOS: bun PATH below.
Claude Code
The quickest route is the CLI:
The server is available immediately in the current session.
Alternatively, add to .mcp.json at your project root (or ~/.claude.json for a user-scoped server):
If you edit the file directly, restart the Claude Code session to pick it up.
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):
Restart Claude Desktop. You should see hey listed as an available integration.
Cursor
Add to ~/.cursor/mcp.json:
Restart Cursor.
Docker
A Dockerfile is included for containerised deployments and Glama compatibility.
**Build the image:**
**Smoke-test the server** (should return a JSON-RPC response listing available tools):
> **Note:** The Docker image runs the MCP server only. The Python auth helper and webview login are not available inside the container. You must provide pre-existing session cookies via a volume mount to data/hey-cookies.json for authenticated operations.
macOS: bun PATH
GUI apps (Claude Desktop, Cursor) and shells launched by Claude Code don't always inherit the PATH from your interactive terminal, so a Homebrew-installed bun may fail with spawn bun ENOENT or simply never connect. Fix by using the absolute path to bun in command:
- **Apple Silicon Homebrew** — /opt/homebrew/bin/bun
- **Intel Homebrew** — /usr/local/bin/bun
- **Manual install** — run which bun in your terminal to find it
Example:
Architecture
| Component | Description |