MCP Hey

What Sealjay/mcp-hey MCP server does

Sealjay/mcp-hey MCP server connects an MCP client to a Hey.com account using the same web session established through Hey's login page. It supports reading messages from inbox-related areas such as Imbox, Feed, Paper Trail, Set Aside, Reply Later, Drafts, Trash, and Spam. Agents can also search mail, inspect threads, download attachments, and parse calendar invitations.

The write surface covers sending, replying, and forwarding email. Mail organization includes labels, collections, set-aside and reply-later actions, moving messages, read-state changes, thread muting, bubble-up operations, and screener decisions. A cache-status tool reports information about the local cache.

How it works

The Sealjay/mcp-hey MCP server runs as a Bun and TypeScript process using MCP stdio transport. An MCP client launches the server locally and exchanges tool calls through standard input and output; the server does not open a network listener.

On first authentication, the Python helper opens Hey.com in the system webview. After the user signs in, it writes session cookies to data/hey-cookies.json. Later launches reuse those cookies until the session expires. Requests go directly to Hey.com with browser-like request details, and returned content is parsed before being stored in SQLite. The cache stores messages, threads, and a full-text search index for repeated reads.

Because Hey does not provide a documented public API, the project relies on reverse-engineered web endpoints. Those endpoints may change without notice. Write requests fetch a current CSRF token before submitting changes.

Setup and configuration

The project requires Bun 1.1 or newer, Python 3.10 or newer, and a Hey.com account. The documented development platforms are macOS and Linux. Windows is not exercised directly; WSL may be needed.

Installation is repository-based: clone the project, run bun install, and install the Python helper dependencies with uv pip install -r auth/requirements.txt. Run bun run dev for the initial login. After the webview saves the cookie file, configure the MCP client to launch bun run /absolute/path/to/mcp-hey/src/index.ts.

Claude Code, Claude Desktop, and Cursor configuration examples are provided. GUI clients on macOS may need an absolute path to the Bun executable because their environment may not include the interactive shell's PATH. A Dockerfile is also included, but its container does not provide the Python webview login; authenticated container use requires mounting an existing cookie file at data/hey-cookies.json.

Tools and capabilities

The Sealjay/mcp-hey MCP server documents 34 tools in these groups:

• Reading mailbox areas, summaries, individual messages, attachments, and calendar invites
• Searching email and checking cache status
• Managing labels and collections
• Sending, replying to, and forwarding messages
• Applying triage and read-status actions
• Bubbling threads up or removing them from bubble-up
• Screening senders or messages in and out

Tool names, parameters, return formats, and error behavior are documented in the repository's tool reference.

Limitations and notes

This project uses an unofficial Hey.com interface rather than a stable public API, so Hey changes can break functionality. Authentication depends on a local system webview and a valid session cookie file. The cookie file is written with restrictive 600 permissions, but it remains sensitive local session data.

The project states that it stores no passwords or other credentials, emits no telemetry, and keeps data on the local machine. Its idle memory use is described as approximately 30 MB. Container deployments cannot perform the interactive webview login internally.