# marlinjai/email-mcp [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/marlinjai/email-mcp  
**GitHub Stars:** 19  
**npm Downloads (last month):** 2532  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/marlinjai-email-mcp

## Description
Unified MCP server for email across Gmail (REST API), Outlook (Microsoft Graph), iCloud, and generic IMAP/SMTP. 24 tools for search, send, organize, and batch-manage emails with built-in OAuth2 and encrypted credential storage.

## Tools
Capabilities this server exposes over MCP:

- **email_list_accounts** — List all configured email accounts and their connection status
- **email_add_account** — Add a new IMAP or iCloud email account (Gmail and Outlook require the setup wizard for OAuth)
- **email_remove_account** — Remove an email account
- **email_test_account** — Test an email account connection
- **email_list_folders** — List all email folders for an account
- **email_search** — Search emails with filters. By default returns compact results without full body content to save context. Set returnBody=true to include full email bodies.
- **email_get** — Get a single email by ID
- **email_get_thread** — Get an email thread by thread ID
- **email_get_attachment** — Get an email attachment by ID, returns base64 encoded data
- **email_save_attachment** — Download an email attachment and save it directly to disk, returning metadata only (no base64 in the response) — avoids paying the token cost of round-tripping large attachments through the calling model. outputPath is relative to a fixed downloads directory (/home/user/.email-mcp/downloads, override with EMAIL_MCP_DOWNLOADS_DIR) and cannot escape it.
- **email_send** — Send a new email
- **email_reply** — Reply to an existing email
- **email_forward** — Forward an email to new recipients
- **email_draft_create** — Create a new email draft
- **email_draft_list** — List email drafts
- **email_move** — Move an email to a different folder
- **email_delete** — Delete an email (moves to trash by default, or permanently deletes)
- **email_mark** — Mark an email as read/unread, starred, or flagged
- **email_batch_delete** — Delete multiple emails at once. Much faster than individual deletes.
- **email_batch_move** — Move multiple emails to a folder at once. Much faster than individual moves.
- **email_batch_mark** — Mark multiple emails at once (read/unread, starred, flagged). Much faster than individual marks.
- **email_transfer** — Move or copy emails BETWEEN accounts, preserving the original message intact (sender, date, threading) by transferring the raw MIME. Fetches each message from the source account and imports it into the target account. With deleteAfter=true the source copy is sent to trash only after a confirmed import, making this a safe cross-account move.
- **email_label** — Add or remove labels on an email (Gmail only)
- **email_folder_create** — Create a new email folder
- **email_get_labels** — List all labels for an email account (Gmail only)
- **email_get_categories** — List all categories for an email account (Outlook only)
- **email_report_spam** — Report an email as spam/junk, training the provider's own spam filter (the same signal the "Report Junk" button sends in Gmail/Outlook). This is different from email_delete, which removes the message but teaches the filter nothing. Not an abuse report to the provider's security team — it only trains this account's filter.
- **email_batch_report_spam** — Report multiple emails as spam/junk at once. Much faster than individual calls.
- **email_create_block_rule** — Create a standing rule that intercepts future mail matching a pattern, before it reaches the inbox. Use headerContains (e.g. matching a Reply-To domain) to block a spam template family whose visible "From" domain rotates — matching the rotating domain directly stops working within days. Not supported on iCloud/generic IMAP (no standard server-side rule mechanism exists across IMAP servers). Outlook requires the MailboxSettings.ReadWrite scope — accounts authenticated before this tool existed need to re-run the setup wizard once to re-consent.
- **email_list_block_rules** — List the standing block rules on an account, for auditing or before deleting one.
- **email_delete_block_rule** — Delete a standing block rule — use this to undo a rule that turned out to be too broad (e.g. it blocked a domain a real correspondent also uses).

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

## Documentation

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

_Full upstream README: https://allmcps.com/mcp/marlinjai-email-mcp/readme_