mcp-hey is a locally running Model Context Protocol (MCP) server that provides Claude and any MCP-compatible client with read and write access to Hey.com email. Under the hood, it is not an official public API, but rather a reverse-engineered wrapper around the Hey.com web interface, paired with browser-consistent HTTP request headers and TLS characteristics to reduce the risk of being identified. The project runs entirely locally, does not rely on cloud relays, and does not store account credentials; it only saves session cookies on disk.
mcp-hey consists of two parts: an MCP server written in Bun/TypeScript that exposes Hey-related tools via stdio, and a Python helper script that captures session cookies at login with the help of the system webview.
Main capabilities include: reading emails under categories such as Imbox, Feed, Paper Trail, Set Aside, Reply Later, Drafts, Trash, and Spam; downloading attachments and parsing calendar invitations in emails; sending and replying to email threads; searching emails across inboxes; organizing emails (setting aside, replying later, screening in/out, pinning, etc.). The server uses a local SQLite cache to speed up repeated reads and provide full-text search, with idle memory of about 30 MB.
Usage: requires Bun 1.1+, Python 3.10+ (and UV if you need to operate according to the Python toolchain in CLAUDE.md) and a Hey.com account. The development and testing environment is macOS and Linux; Windows users may need WSL. To install, clone the repository and then run bun install and uv pip install -r auth/requirements.txt. The first run of bun run dev will open the Hey.com login page in the system webview; after logging in, the helper script writes the session cookies to data/hey-cookies.json (permissions 600) and exits; afterward, the MCP client will start a server instance on its own until the session expires. Then you need to configure the startup command in the MCP client (Claude Code, Claude Desktop, Cursor, etc.), usually bun run src/index.ts. In macOS graphical applications, it may be necessary to use the absolute path of bun. The project also provides a Dockerfile, but the container does not include the Python authentication helper or webview login; existing session cookies must be provided via a mounted volume. On startup, the server validates the cookie file; if it is missing or expired, it attempts to launch the authentication script. Tool calls directly request Hey.com, parse the HTML, and cache it in SQLite; before write operations, it obtains a new CSRF token. A total of 34 tools are provided; see docs/TOOLS.md for details.
Regarding privacy and security: no passwords or credentials are stored, only session cookies with 600 permissions are written; authentication is completed entirely within Hey's own login page; all data remains on the local machine, and the project does not send telemetry; MCP uses stdio transport, and the server does not open network listeners; session validity is checked at startup and before sensitive operations.
Limitations and risks: it uses an unofficial API, and changes to the Hey.com frontend may cause functionality to fail; pay attention to docs/API.md; only polling is supported, with no real-time notifications; attachment upload is not currently supported; each MCP server instance supports only a single account; abnormal access patterns could theoretically trigger Hey's anti-abuse mechanisms; although the server follows the x-ratelimit header and uses exponential backoff, this is not guaranteed; only the English interface is supported, and the server parses English HTML strings (such as "You ignored this thread", label names, button text), so it does not work correctly under non-English locales; like many MCP servers, there is a prompt injection risk (the lethal trifecta), and malicious emails may attempt to instruct Claude to leak other messages, so review should be performed before approving sensitive operations.
Common issues: if the authentication webview does not open, confirm that Python 3.10+ and dependencies are installed, and that the webview backend is available on Linux; 401/403 indicates the session has expired; delete data/hey-cookies.json and rerun bun run dev; 429 is rate limiting, and the client will automatically back off; if it persists, reduce concurrency or wait a while; if the MCP client cannot start the server, args must use absolute paths; if bun reports spawn bun ENOENT, refer to the solution for bun PATH on macOS; cookie name changes (such as _hey_session changed to session_token) may cause authentication to fail silently, and cookies need to be recaptured and checked against the documentation.
The project is released under the MIT license, and contributions via PR are welcome. Conventional commits are recommended, run bun run format and bun run lint before pushing, make sure bun test passes, and update docs/API.md when discovering or modifying Hey.com API behavior.
