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).

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

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.