hey-mcp

MCP server that gives Claude full access to HEY email, calendars, todos, habits, time tracking, and journal. Built on FastMCP, it wraps the hey-cli command-line tool.

The server intentionally runs the HEY CLI on the host machine. That lets isolated Claude Cowork workspaces use the host's existing hey-cli authentication without copying tokens or keychain material into the workspace.

Prerequisites

• Python 3.11+
• uv package manager
• hey-cli installed and authenticated on the host

Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

Install and authenticate hey-cli

Follow the hey-cli installation instructions, then authenticate:

hey auth login

By default the MCP server looks for the host CLI in this order:

1. HEY_CLI_BIN
2. HEY_BIN
3. /usr/local/bin/hey
4. /usr/local/sbin/hey
5. /opt/homebrew/bin/hey
6. ~/.local/bin/hey
7. hey on $PATH
8. ~/dev/hey/cli/bin/hey

Set HEY_CLI_BIN=/absolute/path/to/hey in your MCP server environment if you want to pin it to a specific build.

Installation

git clone https://github.com/cpinto/hey-mcp.git
cd hey-mcp
uv sync

Configuration

Claude Desktop

Add the following to your claude_desktop_config.json (on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "hey": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/hey-mcp", "run", "main.py"],
      "env": {
        "HEY_CLI_BIN": "/absolute/path/to/hey"
      }
    }
  }
}

Replace /absolute/path/to/hey-mcp and /absolute/path/to/hey with the actual paths for your host.

Claude Code

Add the same config to your Claude Code settings (~/.claude/settings.json):

{
  "mcpServers": {
    "hey": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/hey-mcp", "run", "main.py"],
      "env": {
        "HEY_CLI_BIN": "/absolute/path/to/hey"
      }
    }
  }
}

Installing the Skill

The repo includes a SKILL.md file that teaches Claude Code when and how to use the HEY MCP tools. To install it:

mkdir -p ~/.claude/skills/hey
cp SKILL.md ~/.claude/skills/hey/SKILL.md

Or symlink it so updates pull automatically:

mkdir -p ~/.claude/skills/hey
ln -sf "$(pwd)/SKILL.md" ~/.claude/skills/hey/SKILL.md

Once installed, Claude Code will automatically invoke the HEY tools when you mention emails, todos, calendar, journal, etc.

Available Tools

Tool	Description
run_hey_command	Run any non-interactive host hey command; backstop for newly added CLI features
list_boxes	List all HEY mailboxes
list_postings	List emails in a mailbox
read_thread	Read a full email thread
list_attachments	List attachments in an email thread
download_attachments	Download attachments from a thread onto the host filesystem
compose_email	Compose and send a new email, or save it as a draft
reply_to_thread	Reply to an email thread, or save a reply draft
list_drafts	List email drafts
mark_seen	Mark postings as seen
mark_unseen	Mark postings as unseen
list_calendars	List all HEY calendars
list_recordings	List calendar events, todos, habits
create_event	Create a calendar event
update_event	Update a calendar event
delete_event	Delete a calendar event
list_todos	List all todos
add_todo	Create a new todo
complete_todo	Mark a todo as complete
uncomplete_todo	Mark a todo as incomplete
delete_todo	Delete a todo
complete_habit	Mark a habit as complete
uncomplete_habit	Remove a habit completion
timetrack_start	Start time tracking
timetrack_stop	Stop time tracking
timetrack_current	Show current timer status
timetrack_list	List time tracking entries
journal_list	List journal entries
journal_read	Read a journal entry
journal_write	Write or edit a journal entry
list_commands	List commands exposed by the host HEY CLI
auth_status	Show host CLI authentication status
auth_refresh	Refresh the host CLI access token
auth_token	Print the host CLI access token
auth_logout	Clear host CLI credentials
show_config	Show host CLI configuration
set_config	Set host CLI configuration
doctor	Check host CLI health and configuration
setup	Run the host CLI first-run setup command

List tools support the CLI's current pagination flags where available: limit and fetch_all. Calendar event tools support invitees and reminders, matching the CLI's --invitee and --reminder flags.

License

MIT