Email MCP

@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:

npm install -g @marlinjai/email-mcp

Or run directly with npx (no install needed):

npx @marlinjai/email-mcp

Quick Start

1. Run the interactive setup wizard to add your email accounts:

npx -y -p @marlinjai/email-mcp@latest email-mcp-setup

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.

1. Add the server to your MCP configuration (.mcp.json):

{

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

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

npx -y -p @marlinjai/email-mcp@latest email-mcp-setup

Select "Gmail" when prompted

Choose "Full" or "Restricted" permission scope when asked

A browser window opens for Google authorization

Grant the requested permissions and return to the terminal

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

npx -y -p @marlinjai/email-mcp@latest email-mcp-setup

Select "Outlook" when prompted

A browser window opens for Microsoft authorization

Sign in and grant the requested permissions

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.

iCloud

1. Go to appleid.apple.com and sign in.
2. Navigate to App-Specific Passwords and generate a new password.
3. Run the setup wizard:

npx -y -p @marlinjai/email-mcp@latest email-mcp-setup

Select "iCloud" when prompted

Enter your iCloud email address

Enter the app-specific password you generated

Generic IMAP

Run the setup wizard with your IMAP/SMTP server details:

npx -y -p @marlinjai/email-mcp@latest email-mcp-setup

Select "Other IMAP" when prompted

Enter your IMAP host, port, and credentials

Optionally enter SMTP host and port for sending

Available Tools (36)

Account Management (4)

Reading & Searching (6)

Sending & Drafts (6)

email_send, email_reply, email_forward, email_draft_create and email_draft_update take an optional attachments list. Each entry is either { path } (a file in the attachments folder, see below) or { content, filename } (base64), with an optional contentType (inferred from the extension otherwise). The total is capped at 25 MB; Outlook accepts up to 3 MB per message through this server. On email_draft_update a list replaces the draft's files, an empty list removes them, and no list keeps the files the draft has.

Gmail adds your signature, like Gmail's own editor. The Gmail API never appends one, so email_send, email_reply, email_forward, email_draft_create and email_draft_update read the signature of the send-as address the mail goes out from (Gmail settings, read on every call, so a changed signature applies at once) and add it in Gmail's own markup (gmail_signature), above any quoted history, plus a plain-text rendering in the text part. A text-only body gains an HTML part for it, as the signature's logo and links only exist as HTML. A body that already holds a signature (a gmail_signature block, or a -- line in text) is left alone, so passing a draft's body back to email_draft_update never stacks a second one. signature: false turns it off for one call. Each of these tools returns a signature field saying what happened: added, already_present, disabled, none_configured, unsupported, or skipped with the reason (for example a missing permission); a failed read never blocks the mail or draft.

Outlook, iCloud and IMAP add no signature. Microsoft Graph has no signature API for Outlook.com accounts (signatures live in the Outlook clients, out of reach for a server), and an IMAP or iCloud server keeps no signature at all. The tools report unsupported there instead of inventing one; put the signature in the body when the mail needs it. A signature stored in email-mcp's own account settings was considered and left out on purpose: it would be a second copy that drifts from the one in the mail client, which is exactly how old mail ends up with an outdated signature.

From names you. The From header carries a display name, not just the address: on Gmail the send-as display name from Gmail's settings, otherwise the account's name in email-mcp (unless that is only a label: a provider name such as "Gmail" or "iCloud", or the address's local part such as "founder"). Gmail often keeps no display name for an account's primary address (its web editor then uses the Google profile name, which this server cannot read); set one under Settings, Accounts, "Send mail as", edit info, and the tools use it. This also holds for a draft sent later from another mail program, which keeps the draft's From. Outlook sets From itself.

Replies stay in their thread: email_reply sends inside the original conversation on Gmail and Outlook (and sets the In-Reply-To and References headers everywhere), email_draft_create with inReplyToEmailId saves a reply draft in that thread, and email_draft_update keeps a reply draft there.

Forwarding the original message's attachments is opt-in. email_forward sends the text of the original; its files go along only with includeOriginalAttachments: true, so one call does not pass files the assistant never looked at on to another address. Forwarded files count against the 25 MB cap together with added ones.

Attaching files by path is off until you name a folder. The path comes from the assistant, and an assistant that reads mail can be asked by a mail to attach something it should not (a private key, for example). So files are only read from the one folder you set in EMAIL_MCP_ATTACHMENTS_DIR, in the environment of the server; no tool can change it. Put the file there and ask for it by name:

{

"mcpServers": { "email": { "command": "npx", "args": ["@marlinjai/email-mcp"], "env": { "EMAIL_MCP_ATTACHMENTS_DIR": "~/Documents/email-outbox" } } } }

A path outside that folder is refused, as is a symbolic link that leads out of it, and email-mcp's own data files are ne