hey_list_emailsLABSCO SUMMARY
Hey's triage vocabulary, exposed as tools instead of buttons.
The value here is that Set Aside, Reply Later, the Screener and Bubble Up all became callable, so an assistant can work the inbox the way Hey expects rather than treating it as a generic mailbox. Two things to weigh before you commit: it rides an API Hey does not publish, so a frontend change can break it, and it parses English-language strings out of Hey's HTML, so a non-English locale will not work.
What it is
A local server for the Hey.com inbox, built as a Bun/TypeScript stdio server plus a small Python helper that captures your session through the system webview at login. Hey does not publish a public API, so this reverse-engineers its web endpoints.
What you get
hey_list_emailsreads Imbox, Feed, Paper Trail, Trash, Spam and Drafts;hey_imbox_summaryreturns screener count, bubbled-up mail and new mail in one callhey_read_emailreturns the body plus attachment metadata and parsed calendar invites;hey_download_attachmentwrites bytes to disk andhey_get_calendar_inviteparses an .icshey_send_email,hey_replyandhey_forwardwrite back- Triage is the whole Hey vocabulary:
hey_set_aside,hey_reply_later,hey_screen,hey_move_to,hey_mark_seen,hey_thread_mute hey_bubble_up,hey_bubble_up_if_no_replyandhey_pop_bubblecover the resurface-later stackhey_searchhits a local full-text cache first, then the network;hey_cache_statusreports what is cached
Requirements
Bun 1.1 or later and Python 3.10 or later, run from a clone over stdio. The first run opens Hey's own login page in a system webview and writes session cookies to data/hey-cookies.json with 600 permissions — no password is stored. Developed and tested on macOS and Linux.
Setup effort
Build from source — git clone https://github.com/Sealjay/mcp-hey.git
USE CASES
01
Clearing the morning inbox
Get the summary, read what matters, and push the rest into Set Aside or Reply Later in the same pass.
02
Deciding on new senders
List who is waiting in the Screener and let them in or keep them out.
03
Finding an old thread and answering it
Search the local cache for speed, open the thread, and reply in place.
04
Getting an attachment or invite out of a message
Save the file to disk, or read the meeting details straight out of the .ics.
37 tools
Listed in project docs. Your client may show a different list.
hey_imbox_summaryhey_list_set_asidehey_list_reply_laterhey_list_screenerhey_read_emailhey_download_attachmenthey_get_calendar_invitehey_list_labelshey_list_label_emailshey_labelhey_list_collectionshey_list_collection_emailshey_collectionhey_send_emailhey_replyhey_forwardhey_save_drafthey_edit_drafthey_delete_drafthey_set_asidehey_unset_asidehey_reply_laterhey_remove_reply_laterhey_move_tohey_set_statushey_mark_unseenhey_mark_seenhey_read_statushey_thread_mutehey_bubble_uphey_bubble_up_if_no_replyhey_pop_bubblehey_screenhey_screen_by_idhey_searchhey_cache_statusBEFORE YOU INSTALL
What to know first
Tools you get
37 tools named in the project's documentation.
Requires
- Bun 1.1 or later
- Python 3.10 or later
INSTALLATION
Connect your client
You clone this one yourself.
Server setup
TERMINAL
git clone https://github.com/Sealjay/mcp-hey.git
cd mcp-hey
bun install
uv pip install -r auth/requirements.txt
bun run devA system webview opens with Hey.com's login page. Log in normally; the helper captures session cookies to data/hey-cookies.json and exits. Press Ctrl+C — your MCP client will launch its own server instance from here on.
MCP Clients
Claude Code
CLAUDE CODE · JSON
{
"mcpServers": {
"hey": {
"type": "stdio",
"command": "bun",
"args": [
"run",
"<YOUR_PATH_TO_MCP_HEY>/src/index.ts"
]
}
}
}Claude Desktop, Cursor
JSON
{
"mcpServers": {
"hey": {
"command": "bun",
"args": [
"run",
"<YOUR_PATH_TO_MCP_HEY>/src/index.ts"
]
}
}
}Docker
DOCKER · TERMINAL
docker build -t mcp-hey .
docker run -i mcp-heymacOS GUI clients
MACOS GUI CLIENTS · JSON
{
"mcpServers": {
"hey": {
"command": "/opt/homebrew/bin/bun",
"args": [
"run",
"<YOUR_PATH_TO_MCP_HEY>/src/index.ts"
]
}
}
}
