@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
接入你的智能体
發布者自己的指令。不是 PlugMCP 端點。
用我們的金鑰與日誌託管一份副本。
npx -y @marlinjai/[email protected]Claude Code 沒有本機指令的安裝連結。複製下方指令並在終端機中執行。
claude mcp add marlinjai-email-mcp -- npx -y @marlinjai/email-mcp@1.11.0在終端機中執行。
{ "mcpServers": { "marlinjai-email-mcp": { "command": "npx", "args": [ "-y", "@marlinjai/[email protected]" ] } }}claude_desktop_config.json
遠端 URL 還是本機指令? 兩種安裝方式的差異
來自發布者
A unified MCP server for email access across Gmail, Outlook, iCloud, and generic IMAP providers.
Unified MCP server for email access across Gmail, Outlook, iCloud, and IMAP — search, send, organize, and batch-manage emails from any AI assistant
Install globally from npm:
npm install -g @marlinjai/email-mcp
Or run directly with npx (no install needed):
npx @marlinjai/email-mcp
npx -y -p @marlinjai/email-mcp@latest email-mcp-setup
The
-p/--packageflag is required. This package declares two binaries (email-mcpfor the MCP server,email-mcp-setupfor this wizard). Without-p, npx runs the bin matching the package's own name (email-mcp, the server) and silently passesemail-mcp-setupto 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.-ptells 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.
.mcp.json):{
"mcpServers": {
"email": {
"command": "npx",
"args": ["@marlinjai/email-mcp"]
}
}
}
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:
https://mail.google.com/, Gmail's maximum-permission scope).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_IDandEMAIL_MCP_GMAIL_CLIENT_SECRETin 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.
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 foremail_create_block_rule), andoffline_accesspermissions, then setEMAIL_MCP_OUTLOOK_CLIENT_IDin the environment before running 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
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
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.
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 never attachable.
All batch tools accept a sourceFolder parameter for IMAP/iCloud and include a sequential fallback for maximum compatibility.
Gmail and Outlook only for the rule tools; email_report_spam/email_batch_report_spam work on every provider (iCloud/IMAP fall back to a best-effort move into the account's Junk-typed folder, with no vendor ML training signal since generic IMAP has none to train).
Gmail and Outlook only. iCloud and generic IMAP have no server-side rule mechanism; set the rule in the provider's own settings there.
Forwarding is off until you allow a target. A standing forward rule copies future mail out of your mailbox, and an assistant that reads mail can be asked to create one by the mail it reads. So email_create_forward_rule only accepts addresses you listed yourself in EMAIL_MCP_FORWARD_ALLOWLIST (comma-separated), in the environment of the server. No tool can change that list:
{
"mcpServers": {
"email": {
"command": "npx",
"args": ["@marlinjai/email-mcp"],
"env": { "EMAIL_MCP_FORWARD_ALLOWLIST": "[email protected]" }
}
}
}
On Gmail the target must also be a forwarding address of the account: add it once under Gmail Settings, "Forwarding and POP/IMAP", "Add a forwarding address", and confirm the email Google sends to it. Outlook needs no such step, which is why the allowlist exists. Outlook accounts authenticated before the block-rule tools existed need to re-run the setup wizard once, as for those tools.
Add the following to your .mcp.json file (project-level or global ~/.claude/.mcp.json):
{
"mcpServers": {
"email": {
"command": "npx",
"args": ["@marlinjai/email-mcp"]
}
}
}
Once configured, you can ask Claude to interact with your email:
# Install dependencies
pnpm install
# Build the project
pnpm build
# Run in development mode (watch for changes)
pnpm dev
# Run tests
pnpm test
# Run tests in watch mode
pnpm test:watch
# Run integration tests (requires real email accounts)
pnpm test:integration
Account credentials are encrypted at rest with AES-256-GCM in ~/.email-mcp/credentials.enc.
By default the encryption key is derived from a stable, machine-specific identifier
(the hardware UUID on macOS, /etc/machine-id on Linux, or the MachineGuid on
Windows), falling back to the hostname when none is available.
Set the EMAIL_MCP_KEY environment variable to supply your own passphrase instead.
This is recommended when the machine identifier may change (for example in
containers or CI), or when you want to move credentials.enc between machines:
export EMAIL_MCP_KEY="your-strong-passphrase"
When EMAIL_MCP_KEY is set, existing credential files are transparently
re-encrypted with the passphrase the next time they are read.
The Outlook refresh token lives in the token cache of Microsoft's authentication
library (MSAL), ~/.email-mcp/msal-cache.enc, encrypted with the same scheme and key
derivation as credentials.enc, so EMAIL_MCP_KEY protects both files. Versions before 1.8.0
kept this cache as plain JSON in ~/.email-mcp/msal-cache.json; 1.8.0 encrypts it and
deletes the plain file the first time it reads it, without signing you out. Going back
to an older version afterwards means signing in to Outlook again.
On macOS and Linux, attachments saved with email_save_attachment are written
owner-only (0600), and folders email-mcp creates for them are 0700. They are not
encrypted.
The OAuth sign-in callback started by email-mcp-setup listens on the loopback
addresses only (127.0.0.1, and ::1 when available), so nothing else on your network
can reach it.
email-mcp is free and has no paid tier. Its one fixed cost is the independent security assessment Google requires every year for the shared Gmail sign-in (CASA, Cloud Application Security Assessment): 675 US dollars a year. It is the last open step before Google lets everyone use the one-command Gmail setup. Donations are collected until 2 November 2026, the day the assessment has to start, and the maintainer pays what is missing then. Progress is shown at email.lumitra.co.
MIT
Unified MCP server for email access across Gmail, Outlook, iCloud, and IMAP — search, send, organize, and batch-manage emails from any AI assistant
{ "mcpServers": { "marlinjai-email-mcp": { "command": "npx", "args": [ "-y", "@marlinjai/[email protected]" ] } }}工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
@marlinjai/email 透過 stdio 在本機執行。
上次檢查時間:2026-11-12。 Unified MCP server for email access across Gmail, Outlook, iCloud, and IMAP — search, send, organize, and batch-manage emails from any AI assistant