Mcp Hey

@Sealjay

About Mcp Hey

Local MCP server for Hey.com email - read, search, send, reply, and manage the screener via stored session cookies. 41 tools over stdio. Runs entirely locally, stores no credentials.

Config

Add this server to your MCP-compatible client using the configuration below.

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

Tools

`hey_list_imbox`, `hey_imbox_summary`, `hey_list_feed`, `hey_list_paper_trail`, `hey_list_set_aside`, `hey_list_reply_later`, `hey_list_screener`, `hey_list_trash`, `hey_list_spam`, `hey_list_drafts`, `hey_read_email`

`hey_send_email`, `hey_reply`, `hey_forward`

`hey_set_aside`, `hey_unset_aside`, `hey_reply_later`, `hey_remove_reply_later`, `hey_mark_unseen`, `hey_trash`, `hey_restore`, `hey_spam`, `hey_not_spam`, `hey_ignore_thread`, `hey_unignore_thread`

`hey_screen_in`, `hey_screen_in_by_id`, `hey_screen_out`

`hey_search`

`hey_cache_status`

Overview

What is Mcp Hey?

Mcp Hey is a local Model Context Protocol (MCP) server that gives Claude read/write access to your Hey.com inbox via reverse-engineered web APIs. It consists of a Bun/TypeScript MCP server and a Python helper for authentication through a system webview, running entirely on your machine with no cloud relay.

How to use Mcp Hey?

Clone the repository, install dependencies with bun install and pip install -r auth/requirements.txt, then authenticate by running bun run dev and logging into Hey.com. Configure your MCP client (Claude Code, Claude Desktop, or Cursor) by adding the server with bun run /absolute/path/to/mcp-hey/src/index.ts as the command and args. For Docker, build the image and mount pre-existing session cookies.

Key features of Mcp Hey

Read emails from Imbox, Feed, Paper Trail, Set Aside, and Reply Later
Send, reply to, and forward email threads directly from Claude
Search emails across all boxes with full-text search
Organize mail with set aside, reply later, screen in/out, and bubble up
Local SQLite cache for fast repeated reads and search
Lightweight — around 30 MB idle memory with stdio transport

Use cases of Mcp Hey

Manage your Hey.com inbox entirely through Claude using natural language commands
Automate email triage: read, reply, set aside, or trash messages without leaving Claude
Search across Hey.com mailboxes for specific threads or contacts
Organize incoming email by applying labels, collections, or screening rules

FAQ from Mcp Hey

How does authentication work?

A Python auth helper opens a system webview pointed at Hey.com. You log in normally; session cookies are captured to data/hey-cookies.json with 600 permissions. No credentials are ever stored — only session cookies.

What happens when my session expires?

Delete data/hey-cookies.json and run bun run dev again to re-authenticate. Session validity is checked on startup and before sensitive operations.

Is this an official Hey.com API?

No. Mcp Hey reverse-engineers Hey.com's web endpoints and pairs them with browser-identical HTTP requests. Things can break without notice. The known API surface is documented in docs/API.md.

What are the main limitations?

No real-time notifications — polling only.
Attachment uploads are not yet supported.
Single account per MCP server instance.
Prompt-injection risk: a malicious email could attempt to exfiltrate other messages.
Aggressive access patterns may trigger anti-abuse systems (rate limits are respected with exponential backoff).

Frequently asked questions

How does authentication work?

A Python auth helper opens a system webview pointed at Hey.com. You log in normally; session cookies are captured to `data/hey-cookies.json` with `600` permissions. No credentials are ever stored — only session cookies.

What happens when my session expires?

Delete `data/hey-cookies.json` and run `bun run dev` again to re-authenticate. Session validity is checked on startup and before sensitive operations.

Is this an official Hey.com API?

No. Mcp Hey reverse-engineers Hey.com's web endpoints and pairs them with browser-identical HTTP requests. Things can break without notice. The known API surface is documented in `docs/API.md`.

What are the main limitations?

- No real-time notifications — polling only. - Attachment uploads are not yet supported. - Single account per MCP server instance. - Prompt-injection risk: a malicious email could attempt to exfiltrate other messages. - Aggressive access patterns may trigger anti-abuse systems (rate limits are respected with exponential backoff).