email-mcp

Multi-account email MCP server for Gmail, Outlook, and iCloud. Single native binary (Rust), no runtime required, handles OAuth token refresh automatically.

Install

npm install -g @kembec/email-mcp

Supports: macOS (arm64, x64), Linux (x64, arm64), Windows (x64).

Add to your MCP client

Cursor / Claude Desktop

Add to your MCP config (~/.cursor/mcp.json or claude_desktop_config.json):

{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["-y", "@kembec/email-mcp"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "email": {
      "command": "email-mcp"
    }
  }
}

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.email]
command = "npx"
args = ["-y", "@kembec/email-mcp"]
enabled = true

Custom config directory

By default credentials are stored in ~/.config/email-mcp/accounts.json (macOS/Linux) or %APPDATA%\email-mcp\accounts.json (Windows). Override with:

{
  "mcpServers": {
    "email": {
      "command": "email-mcp",
      "env": {
        "EMAIL_MCP_CONFIG_DIR": "/path/to/your/config"
      }
    }
  }
}

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.email]
command = "npx"
args = ["-y", "@kembec/email-mcp"]
enabled = true

Setup

Gmail

1. Create a project in Google Cloud Console
2. Enable the Gmail API
3. Create OAuth2 credentials → Desktop app → copy Client ID and Client Secret
4. Add http://127.0.0.1 to Authorized redirect URIs (any port)

Then call auth_start:

{
  "name": "auth_start",
  "arguments": {
    "provider": "gmail",
    "account_id": "work",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }
}

The tool returns a URL. Open it in your browser, authorize, and the flow completes automatically.

Outlook

1. Register an app in Azure AD
2. Add redirect URI: http://localhost → type: Mobile and desktop applications
3. Copy the Application (client) ID

Then call auth_start:

{
  "name": "auth_start",
  "arguments": {
    "provider": "outlook",
    "account_id": "work",
    "client_id": "YOUR_APP_ID"
  }
}

Outlook uses device code flow: the tool returns a short URL and a code (e.g. https://microsoft.com/devicelogin + code ABCD1234). Open the URL, enter the code, and sign in. Auth completes in the background automatically.

iCloud

1. Go to appleid.apple.com → Sign-In & Security → App-Specific Passwords
2. Generate a password named email-mcp

{
  "name": "auth_add_icloud",
  "arguments": {
    "account_id": "personal",
    "email": "you@icloud.com",
    "app_password": "xxxx-xxxx-xxxx-xxxx"
  }
}

Tools

Tool	Description
list_accounts	List configured accounts and auth status
auth_start	Start OAuth2 for Gmail or Outlook
auth_add_icloud	Add an iCloud account
auth_remove	Remove an account
list_messages	List recent emails (folders: inbox, sent, drafts, trash, spam)
get_message	Get full content of a specific email
send_message	Send an email (supports to, cc)
search_messages	Search emails (Gmail: from:, subject:, has:attachment etc; Outlook: KQL)

All tools require account_id to select the account.

Multi-account

Configure as many accounts as needed, each with a unique account_id:

{ "name": "list_accounts", "arguments": {} }

Credentials storage

Tokens and app passwords are stored in accounts.json in the config directory. The file is only readable by the current user. Never commit this file.

License

MIT