Email MCP

What marlinjai/email-mcp does

The marlinjai/email-mcp MCP server gives an MCP client a unified interface for Gmail, Outlook, iCloud, and generic IMAP/SMTP accounts. It supports account setup and connection checks, folder discovery, filtered message search, full-message retrieval, thread retrieval, sending, replies, forwarding, and draft management.

Organization features cover moving, deleting, marking, labeling, and creating folders. Gmail-specific operations include labels, while Outlook-specific operations include categories. Spam tools report messages to the provider's own spam or junk filter, rather than sending an abuse report to a security team. Standing block rules can intercept future messages matching supported patterns; these rules are unavailable for iCloud and generic IMAP accounts.

How it works

Gmail and Outlook use browser-based OAuth2 flows with automatic token refresh. Gmail can use either a full permission scope or a restricted scope; permanent deletion requires the full scope. iCloud uses an Apple app-specific password, and generic IMAP accounts use the server details and credentials supplied during setup, with optional SMTP settings for sending.

Provider-native APIs are used for Gmail and Microsoft Graph where available. IMAP provides compatibility for iCloud and other supported mail servers. Credentials are stored with AES-256-GCM encryption using machine-derived keys. The server can transfer messages between configured accounts by importing raw MIME data, preserving message content and metadata. When requested, it moves the source copy to trash only after the destination import is confirmed.

Setup and configuration

Install the npm package or run the server with npx. The separate setup wizard walks through provider selection, authentication, and adding multiple accounts. After setup, register the server as an MCP process, using the package's server command rather than the setup wizard.

Gmail and Outlook normally use the OAuth credentials bundled with the package. Developers who need their own OAuth applications can provide Gmail client ID and client secret variables, or an Outlook client ID, before running setup. The downloads directory used by attachment saving defaults to /home/user/.email-mcp/downloads and can be changed with EMAIL_MCP_DOWNLOADS_DIR.

Tools and capabilities

The marlinjai/email-mcp MCP server includes tools for:

• Listing, adding, removing, and testing accounts
• Listing folders, labels, and Outlook categories
• Searching with compact results by default, then retrieving bodies when needed
• Reading individual messages, threads, and attachments
• Saving attachments directly to the configured downloads directory
• Sending, replying, forwarding, and creating or listing drafts
• Moving, deleting, marking, labeling, and creating folders
• Deleting, moving, marking, and reporting spam for multiple messages in one call
• Transferring or copying messages between configured accounts
• Creating and auditing supported standing block rules

Attachment retrieval can return base64 data, while the save operation returns metadata after writing the file locally. Batch operations use provider-specific batching where available and sequential fallback behavior for compatibility.

Limitations and notes

Gmail labels and Outlook categories are provider-specific, so those tools do not provide equivalent functionality across every account type. Block rules require a server-side rule mechanism: they are not supported on iCloud or generic IMAP. Outlook block-rule creation needs the MailboxSettings.ReadWrite permission, and previously authorized accounts may need to complete setup again to grant it.

IMAP messages are immutable for draft updates. On iCloud and generic IMAP, updating a draft deletes the old message and creates a new one, so the returned identifier must replace the previous identifier. Gmail restricted authorization cannot perform an explicit permanent delete. Saved attachment paths are relative to the fixed downloads directory and cannot escape it.

The package README demonstrates configuration for Claude Code. It does not document compatibility with a specific other MCP client.

Getting started with this marlinjai/email-mcp MCP server

Always refer to the official documentation for the most accurate and up-to-date information.