marlinjai/email-mcp

A unified MCP server for email access across Gmail, Outlook, iCloud, and generic IMAP providers.
Features
- **Multi-provider support** -- Gmail (REST API), Outlook (Microsoft Graph), iCloud (IMAP), and generic IMAP/SMTP
- **OAuth2 authentication** -- Browser-based OAuth flows for Gmail and Outlook, with automatic token refresh
- **Full email client** -- Search, read, send, reply, forward, organize, and manage drafts
- **Batch operations** -- Delete, move, or mark hundreds of emails in a single call
- **Lightweight search** -- Compact search results by default (~20KB vs ~1.4MB) with optional full body retrieval
- **Encrypted credential storage** -- AES-256-GCM encryption at rest with machine-derived keys
- **Provider-native APIs** -- Uses Gmail API and Microsoft Graph where available for richer features, falls back to IMAP for universal compatibility
Installation
Install globally from npm:
Or run directly with npx (no install needed):
Quick Start
1. Run the interactive setup wizard to add your email accounts:
> **The -p/--package flag is required.** This package declares two binaries (email-mcp for the MCP server, email-mcp-setup for this wizard). Without -p, npx runs the bin matching the *package's own name* (email-mcp, the server) and silently passes email-mcp-setup to it as an ignored argument — the server then sits waiting for MCP protocol input on stdin forever, producing no output at all. It looks exactly like a hang. -p tells npx explicitly which package to resolve and which of its binaries to actually run.
The wizard will walk you through provider selection and authentication. After each account, it asks if you'd like to add another — so you can set up Gmail, Outlook, and iCloud all in one go.
2. Add the server to your MCP configuration (.mcp.json):
3. Start using email tools in Claude Code — search your inbox, send emails, organize messages, and more.
Provider Setup Guides
Gmail
No configuration needed — the setup wizard handles everything using built-in OAuth credentials (PKCE):
The wizard asks which Gmail permission scope to authorize:
- **Full** (default) — everything below, plus immediate, Trash-bypassing permanent deletion (https://mail.google.com/, Gmail's maximum-permission scope).
- **Restricted** — read, send, label, archive, and move-to-trash (gmail.modify + gmail.settings.basic), but no permanent deletion. Every tool in this server works identically under Restricted except an explicit permanent: true delete, which fails with a Gmail API error instead of succeeding.
Pass --scope full or --scope restricted to skip the prompt, or set EMAIL_MCP_GMAIL_SCOPE=restricted in the environment the wizard runs in.
> **Verification status (1 October 2026):** Google's review of the shared OAuth app is still running, so Google currently only lets accounts on its test-user list sign in through it; everyone else sees the "has not completed the Google verification process" screen and needs their own OAuth app (next note). The last open step for the shared app is a yearly independent security assessment (CASA, Cloud Application Security Assessment) that Google has requested. Because email-mcp has no server of its own, its applicability is being clarified with Google. Details and current status: email.lumitra.co/privacy#google-verification, tracked in issue #1.
> **Note:** If you prefer to use your own OAuth app instead of the shared one this package ships with, create a Desktop OAuth 2.0 Client in the Google Cloud Console with the Gmail API enabled, then set EMAIL_MCP_GMAIL_CLIENT_ID and EMAIL_MCP_GMAIL_CLIENT_SECRET in the environment before running the setup wizard (and in the MCP server's environment, since re-authentication uses the same variables). This gives you your own token lifecycle, independent of the publisher's Cloud project, and sidesteps Google's unverified-app warning and 100-test-user cap for your own account(s) once you add yourself as a test user on your own app.
Outlook
No configuration needed — the setup wizard handles everything using built-in OAuth credentials (PKCE):
> **Note:** If you prefer to use your own OAuth app, register one in the Azure Portal with Mail.ReadWrite, Mail.Send, MailboxSettings.ReadWrite (needed for email_create_block_rule), and offline_access permissions, then set EMAIL_MCP_OUTLOOK_CLIENT_ID in the environment before running the setup wizard.