email-mcp

MCP server (stdio) exposing structured email tools over IMAP/SMTP for multiple accounts: email_list_accounts, email_list_folders, email_search, email_read, email_attachment, email_mark, email_move, email_delete, email_send, email_authenticate.

Setup

npm install
npm run build

Copy accounts.example.json to ~/.config/email-mcp/accounts.json (or set EMAIL_MCP_CONFIG) and fill in your accounts.

• auth.type: "password" — plain IMAP LOGIN / SMTP AUTH. pass is either a literal or a 1Password reference (op://vault/item/field), resolved via op read at first use — the op CLI must be signed in.

• auth.type: "m365-oauth" — Exchange Online / Microsoft 365 via XOAUTH2 device-code flow (basic-auth IMAP is dead there). tenant is your domain or tenant ID; clientId is optional and defaults to Thunderbird's public client. Run the email_authenticate tool once per account; the refresh token is cached at ~/.config/email-mcp/tokens/<account>.json (chmod 600).

• appendToSent: true — copy sent mail to the \Sent folder via IMAP APPEND (for servers that don't save it automatically; keep false for M365/Gmail).

Related MCP server: mail-mcp

Register with Claude Code (user scope)

claude mcp add --scope user email -- node /path/to/email-mcp/dist/index.js

Or in JSON config:

{
  "mcpServers": {
    "email": {
      "command": "node",
      "args": ["/path/to/email-mcp/dist/index.js"],
      "env": { "EMAIL_MCP_CONFIG": "/absolute/path/to/accounts.json" }
    }
  }
}

Skill

Symlink the bundled orchestration skill into your personal skills directory so Claude Code picks it up:

ln -s /path/to/email-mcp/skills/email-manager ~/.claude/skills/email-manager

Rules mode (non-interactive sorting)

email-mcp rules sorts mail by ordered, deterministic rules from YAML files, with an optional LiteLLM classifier for mail no rule matches. It uses the same account config, 1Password references and M365 tokens as the server. With no subcommand, email-mcp still starts the MCP server.

email-mcp rules check <file.yml>...        # validate; exit 0/1
email-mcp rules run <file.yml>... [--dry-run] [--accounts a,b] [--since YYYY-MM-DD]
                                  [--include-read] [--state <path>] [--report <path.json>]
                                  [--no-classifier]
email-mcp rules folders <file.yml>... [--create]

• run handles unread mail in the file's mailboxes by default. Add --since and --include-read for a one-off backlog pass.

• --dry-run still searches, fetches and calls the classifier, but changes nothing and never sets \Seen. It prints the planned action for each message.

• --state remembers messages already decided keep (by a rule or the classifier), so later runs skip them. Entries older than 60 days are pruned.

• --report writes a JSON report. It is written even if the run fails.

• Exit codes: 0 ok, 1 config or validation error, 2 some account failed (the other accounts were still processed).

• folders lists the folders each account's move, map and purge actions target. --create creates the missing ones, but only those listed in create_folders.

version: 1
accounts: [personal, work]       # account names from accounts.json (required)
mailboxes: [INBOX]               # default [INBOX]
unread_only: true                # default true
default_action: keep             # no rule matched and no classifier verdict
sweep_trash_unread: false        # mark unread mail in \Trash read after the pass
account_purpose:                 # optional context line for the classifier
  personal: "personal mail: family, home, bank"
classifier:                      # optional
  provider: luna                 # luna | jev
  min_confidence: 0.6            # below => default_action
  map:                           # verdict -> action; unlisted or "unsure" => default_action
    fyi: read
    finance: {move: Finance, read: true}
    auth: {move: Auth, read: true}
    trash: trash
purge:                           # time-based clean-up of a folder
  - {folder: Auth, older_than: 24h, action: trash}
create_folders:                  # folders `rules folders --create` may create
  personal: [Finance, Auth]
rules:                           # ordered; first match wins
  - id: codes
    accounts: [personal]         # optional filter
    when:                        # all conditions must hold; case-insensitive JS regexes
      from: '@accounts\.example\.com$'
      subject: 'verification code'
    action: {move: Auth, read: true}
  - id: replies
    when: {sent_thread: true}    # subject matches something you sent in the last 90 days
    action: keep

Conditions: from, from_not, from_name, subject, subject_not, to, cc, to_cc, list_id, body (fetched only when a rule reaches that condition), sent_thread, sent_recipient (a sender you wrote to in the last 180 days), and older_than (Nh or Nd). Actions:

• keep: change nothing.

• read: mark read.

• trash: mark read, then move to \Trash. It never expunges.

• {move: F, read: bool}: move to folder F. If F is missing, only the read flag is applied and the report records folder_missing.

• classify: send the message to the classifier.

The classifier calls LiteLLM at LITELLM_BASE_URL using LITELLM_API_KEY. Without either it is skipped for the run and a warning goes in the report. If it fails, the message gets default_action, except that a failure never trashes mail. The Junk folder is never sent to the classifier.

Development

npm test          # vitest unit suite (no network)
npm run build     # tsc → dist/

Manual end-to-end testing: run the server and exercise each tool against a real account.