hey

HEY email CLI and MCP server. Read, search, organize, and send emails from the command line or from Claude.

Built by reverse engineering HEY's web interface (no public API).

Quick Start

npm install
npm run build

# Authenticate (see "Authentication Setup" below)
hey auth

# Grant read access
hey allow read --otp <code> --always

Claude Code

claude mcp add hey -- npx hey

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "hey": {
      "command": "npx",
      "args": ["hey"],
      "cwd": "/path/to/hey"
    }
  }
}

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

CLI

# Email
hey list                    # List imbox (auth emails redacted)
hey list feed               # List newsletters
hey read <id>               # Read a thread
hey read <id> --otp <code>  # Read an auth email (requires OTP)
hey search <query>          # Search emails
hey screener                # Pending sender approvals
hey send [email protected] -s "Subject" -m "Body"

# Auth & Keys
hey auth                    # Login via Playwright + generate permission TOTP
hey keys --status           # Check keychain state
hey keys --export           # Export as portable string
hey keys --import <string>  # Import on another machine

# Permissions
hey allow read --otp <code> --mins 30
hey allow send --otp <code> --always
hey allow send --otp <code> --to [email protected]
hey allow read,sort --cron 8am,5pm --mins 10
hey deny send
hey status

Permissions

Every operation requires an active permission grant. Deny-by-default.

Four capabilities:

| Capability | What it allows | Also grants | |-----------|----------------|-------------| | read | List, read, search emails | — | | sort | Move, trash, spam, screener, mute | read | | draft | Create/edit/delete drafts | read | | send | Send and schedule emails | read, draft |

sort and send are independent — an agent that triages your inbox can't send email, and vice versa.

Granting

Permissions require a TOTP code from your authenticator app (a CLI-specific TOTP, separate from your HEY account 2FA):

hey allow read --otp 123456 --mins 60        # 60 minutes (default)
hey allow sort --otp 123456 --always          # permanent
hey allow send --otp 123456 --to [email protected]  # only to specific recipients
hey allow read,sort --cron 8am,12pm,5pm --mins 10  # recurring windows

Revoking

hey deny send               # immediate, no OTP needed
hey deny read,sort,draft,send  # revoke everything

Auth Email Redaction

Emails that look like password resets, 2FA codes, sign-in links, or verification codes are automatically detected by subject line. In listings and search results, the subject and preview are replaced with a placeholder — the sender, timestamp, and id are still visible. Viewing the full content always requires an OTP code, even with an active read grant:

hey read 12345 --otp 654321

In the MCP server, read_email accepts an otp parameter for the same purpose.

Why

When you delegate email to an agent (MCP server, cron job, automation), you want control over what it can do and for how long. The TOTP gate means granting permissions requires physical access to your authenticator — an agent can't escalate its own privileges.

Transferring to Another Machine

# On your laptop (has 1Password):
hey auth
hey keys --export
# Copy the base64 string

# On your VPS:
hey keys --import <paste_string_here>
hey allow read --otp <code> --always

The export includes session cookies and the CLI TOTP secret. The authenticator app on your phone works on both machines.

Authentication Setup

With 1Password (recommended)

1. Install the 1Password CLI: brew install 1password-cli
2. Sign in: op signin
3. Create (or verify) a 1Password item for HEY with these fields:
   • username — your HEY email address
   • password — your HEY password
   • one-time password — TOTP secret for HEY 2FA
4. Run hey auth — it will ask for the item name, find it, and log in automatically

Sessions last 30+ days. Re-run hey auth when expired.

Without 1Password

Set environment variables before running hey auth:

[email protected] HEY_PASSWORD=yourpassword HEY_OTP=123456 hey auth

The OTP is your current 6-digit 2FA code from whatever authenticator app you use for HEY. You have ~30 seconds to run the command before it expires.

After auth succeeds, cookies are stored in your system keychain. You don't need the env vars again until the session expires.

MCP Tools (24)

All tools are permission-gated. The MCP server returns a clear error if a capability isn't granted.

read: list_emails, read_email, search_emails, search_contacts, list_senders, debug_html

sort: move_to_box, trash_email, untrash_email, mark_as_spam, mark_as_not_spam, mark_as_seen, mark_as_unseen, mute_thread, unmute_thread, list_clearances, screen_in, screen_out

draft: list_drafts, create_draft, update_draft, delete_draft

send: send_email, schedule_email

How It Works

HEY doesn't have a public API. This project:

1. Authenticates via Playwright headless browser (handles 2FA automatically)
2. Stores session cookies in system keychain
3. Makes requests with cookie auth (like a browser)
4. Parses HTML responses with Cheerio
5. Tracks rotating _haystack_session cookie

License

MIT