Give your AI assistant a local bridge to your email.
Search, read, organize, reply to, and send email through supported password- or app-password-based IMAP/SMTP accounts—from Claude, Cursor, Codex, and other MCP clients.
MCP server for IMAP/SMTP email access with environment-based configuration
“Move the completed thread from INBOX to Archive.”
Reply with context
“Reply to the latest message from Alex and keep it in the same thread.”
Handle files
“Save the PDF attachment from that message to my Downloads folder.”
Send polished email
“Send the project update with my text and HTML signature.”
Quick Start
[!IMPORTANT]
Enable IMAP and SMTP for your account before starting. This server currently supports password or app-password authentication; OAuth2 is not yet supported.
Prepare your IMAP/SMTP server details and an app password where supported.
Add the server to your MCP client using one of the configurations below.
Restart or reconnect the client, then ask: “Show me unread emails from today.”
Install Node.js 22.13.0 or newer before configuring your MCP client. All examples use npx -y mcp-mail-server, so there is no need to install the server globally.
Client setup
Open Settings > Developer > Edit Config and add the server to claude_desktop_config.json:
Use --scope local for the current project only (the default), or --scope project to create a shared .mcp.json in the project root. Claude Code does not read MCP servers from .claude/settings.json. Run claude mcp get mcp-mail-server or use /mcp inside Claude Code to verify the connection. See the Claude Code MCP documentation for scope and configuration details.
Export those variables before starting Codex. The ChatGPT desktop app, Codex CLI, and Codex IDE extension share this configuration. See the Codex MCP documentation for current options.
Use your client's current MCP configuration format and register a local STDIO server with:
Command: npx
Arguments: -y, mcp-mail-server
Environment: the required IMAP, SMTP, and account variables listed under Configuration
Configuration file names and schemas are client-specific; do not assume every client accepts the mcpServers JSON format.
Tools at a glance
The server exposes 14 tools, with explicit mailbox references for message operations.
Attachment metadata in get_message, files through save_attachment
Connection Management
check_connection: Connects to IMAP when needed, actively verifies SMTP, and returns structured status
Mailbox Operations
list_mailboxes: No parameters required. Pass mailbox names back exactly as returned, including leading/trailing spaces. Only INBOX is case-insensitive.
Search Operations
search_messages: Combines mailboxes, from, to, subject, body, IMAP keywords, unread, inclusive since, exclusive before, limit, and includeBody. Omit mailboxes to search INBOX and the detected sent mailbox. Date/time searches widen the IMAP calendar-day query by two days on each side, then apply the exact instant locally so the full UTC+14 to UTC-12 INTERNALDATE spread cannot discard valid messages early. All candidates within MAIL_MAX_SEARCH_CANDIDATES are sorted by internal date before limit is applied; wider searches fail with a narrowing hint instead of guessing from UID order. Results are summaries by default. Keywords must be atom-safe custom IMAP keywords; whitespace, control characters, IMAP syntax characters, and system flags are rejected. When includeBody is true, the call fails explicitly if a selected message disappears before hydration or the request-wide response-body budget would be exceeded.
find_unreplied_messages: sender (required), mailboxes (optional, defaults to INBOX), since, before, and limit. Uses In-Reply-To and References with case-sensitive Message-ID matching and equivalent quoting normalized. Date filters select incoming candidates only: replies are checked across Sent thread headers regardless of their storage/import date. Incoming and Sent header scans share MAIL_MAX_SEARCH_CANDIDATES and MAIL_MAX_SEARCH_HEADER_BYTES; exceeding either limit fails explicitly rather than guessing “unreplied.” Messages without Message-ID are returned as unknownMessages instead of being guessed from their subject.
get_messages: mailbox (string), uids (array), uidValidity (number, optional), markSeen (boolean, optional). The call fails before fetching bodies if any requested UID is missing, and fails explicitly if the combined returned bodies exceed MAIL_MAX_RESPONSE_CHARACTERS.
move_message: mailbox (string), uid (number), targetMailbox (string), uidValidity (number, optional). The source UID and target mailbox must already exist. Fails safely unless the server supports MOVE or UIDPLUS. When the server returns a destination UID, the result also refreshes destinationUidValidity so the target reference can be reused safely. If a UIDPLUS fallback creates the destination copy but source cleanup reports an error, the tool reopens the source mailbox, verifies the UID and rolls back \\Deleted when possible. A connection loss before MOVE or COPY confirmation returns isError: true, partial: true, and copyOutcome: "unknown"; a confirmed copy followed by uncertain cleanup returns copyOutcome: "succeeded" plus the verified sourceState, optional sourceDeletedFlag, and destination reference when available. Inspect both mailboxes before retrying either result.
move_messages: mailbox (string), uids (array), targetMailbox (string), uidValidity (number, optional). Moves up to 200 UIDs out of one mailbox in a single call. IMAP offers no atomic multi-message MOVE, so each UID is moved and reported independently and one failure never aborts the remaining UIDs. Before each move, the source mailbox is selected read-write and checked against the UIDVALIDITY captured at the start of the batch, even if the caller omitted uidValidity. Failure recovery cannot leave later moves using a read-only mailbox or stale UIDs. The destination reference is refreshed only after the loop finishes. Returns requestedCount, movedCount, failedCount, movedUids and a per-UID results array that carries the same copyOutcome, sourceState and sourceDeletedFlag diagnostics as move_message. isError is set when any UID failed; inspect every entry whose moved flag is false before retrying that UID.
delete_message: mailbox (string), uid (number), uidValidity (number, optional). Verifies the UID exists and permanently deletes only that UID. If STORE or UID EXPUNGE reports an error, the tool verifies the source UID and rolls back \\Deleted when possible. A transport failure that cannot be confirmed returns a structured outcome: "unknown" instead of claiming the message was not deleted.
delete_messages: mailbox (string), uids (array), uidValidity (number, optional). Permanently deletes up to 200 UIDs from one mailbox in a single call using targeted UID EXPUNGE. Each UID is deleted and reported independently and one failure never aborts the remaining UIDs. Before each deletion, the explicit source mailbox is selected read-write and checked against the UIDVALIDITY captured at the start of the batch, even if the caller omitted uidValidity; failed selection or changed UIDVALIDITY prevents that UID from being deleted. Returns requestedCount, deletedCount, failedCount, deletedUids and a per-UID results array carrying the same outcome and stage diagnostics as delete_message. isError is set when any UID failed; inspect every entry whose deleted flag is false before retrying that UID.
Email Sending
send_email: to (string), subject (string), text (string, optional), html (string, optional), signature (object, optional: text and/or html), cc (string, optional), bcc (string, optional), attachments (string[], optional, absolute file paths). At least one of text or html is required.
reply_to_email: mailbox (string), originalUid (number), uidValidity (number, optional), text (string, optional), html (string, optional), signature (object, optional: text and/or html), replyToAll (boolean, default: false), includeOriginal (boolean, default: true). At least one of text or html is required.
continue_email_thread: subject (string), recipient (string, optional narrowing match), since (string, optional), text (string, optional), html (string, optional), signature (object, optional), replyToAll (boolean, default: true), and includeOriginal (boolean, default: true). Finds the newest exact normalized subject in the detected sent mailbox, requires a Message-ID, then replies to that sent message so recurring reports remain in one thread and carry the complete previous body forward, subject to MAIL_MAX_BODY_CHARACTERS.
Natural-language example for a recurring report:
Continue the "Development Daily Report" thread that I sent to [email protected] today. Do not start a new thread. Add: "Completed the mail reply fix today; plan to finish regression testing tomorrow." Keep the complete previous message content and reply to all recipients.
Include "continue/reply to the previous message", the exact subject, a recipient or date, and the new body to help the client select continue_email_thread instead of starting a new thread with send_email.
Signatures are appended after the new message body. In replies, the signature is placed before the quoted original message. Provide both signature.text and signature.html for the best compatibility across mail clients; HTML signatures are treated as trusted email markup.
Outgoing HTML inherits a cross-platform system font stack (Segoe UI/PingFang SC/Microsoft YaHei/Noto Sans CJK SC with Arial and sans-serif fallbacks), a 14px base size, and a 1.6 line height. Explicit styles inside supplied HTML still override these defaults. When callers provide only text, the server preserves the text/plain body and automatically derives an equivalent styled text/html alternative, so HTML-capable clients do not fall back to a monospace plain-text display.
When includeOriginal is enabled, an HTML-only original is converted to readable plain text for the text alternative. Oversized quoted content is truncated to MAIL_MAX_BODY_CHARACTERS while preserving the new reply and signature.
After SMTP accepts a message, sending tools report sentFolderSaved and the detected sentFolder. Sent-mailbox candidates are retried only after a definite non-append; an ambiguous transport failure stops immediately to avoid duplicates. If saving fails, SMTP success is preserved and sentFolderError reports a password-redacted stage, code, message, mailbox, and per-candidate attempts when available.
Attachment Operations
get_message returns attachment filename, content type, size, and index with the message
save_attachment: mailbox (string), uid (number), uidValidity (number, optional), savePath (string, absolute path), attachmentIndex (number, optional, 0-based), attachmentFilename (string, optional, exact match), returnBase64 (boolean, optional, default: false). Select by index or filename, not both; duplicate filenames must be selected by index. Omit both selectors to save all attachments. When saving multiple attachments, a later write failure returns isError: true, partial, savedFiles, and failedAttachment so a retry does not silently duplicate files.
Configuration
Environment Variables
Core mail variables are required. File and security policy variables are optional.
Variable
Description
Example
IMAP_HOST
IMAP server address
imap.gmail.com
IMAP_PORT
IMAP port number, 1-65535
993
IMAP_SECURE
Must be true; use an implicit TLS IMAP endpoint, normally port 993
true
SMTP_HOST
SMTP server address
smtp.gmail.com
SMTP_PORT
SMTP port number, 1-65535
465
SMTP_SECURE
Use implicit TLS on port 465; set false on port 587 to require STARTTLS before authentication
Existing attachment read/write roots. Local attachment access is disabled when unset. Separate roots with : on macOS/Linux or ; on Windows
/Users/me/Documents:/tmp/mail
MAIL_MAX_ATTACHMENT_BYTES
Per-attachment and total attachment limit; defaults to 25 MiB, maximum 1 GiB
26214400
MAIL_MAX_MESSAGE_BYTES
Maximum bytes parsed in memory for one message; defaults to 25 MiB, maximum 1 GiB
26214400
MAIL_MAX_BASE64_BYTES
Maximum attachment size returned as Base64; defaults to 1 MiB, maximum 100 MiB
1048576
MAIL_MAX_BODY_CHARACTERS
Maximum returned characters for each text or HTML body; defaults to 200000, maximum 10000000
200000
MAIL_MAX_RESPONSE_CHARACTERS
Maximum combined text and HTML characters returned by one body-reading tool call; defaults to 2000000, maximum 100000000
2000000
MAIL_MAX_SEARCH_CANDIDATES
Maximum message headers inspected across one search or reply-state tool call; defaults to 5000, maximum 100000
5000
MAIL_MAX_SEARCH_HEADER_BYTES
Maximum raw requested-header bytes buffered across one search or reply-state tool call; defaults to 16 MiB, maximum 1 GiB
16777216
Search results include sourceMailbox, uid, and uidValidity. Pass these values back unchanged when reading, replying, moving, downloading attachments, or deleting so identical UIDs in different mailboxes cannot resolve to the wrong message. Unstable IMAP sequence numbers are not exposed as message IDs. size is the server-provided RFC822 byte size and is null when the server omits it. Search returns summaries by default; use get_message for full bodies and attachment metadata, or set includeBody: true explicitly.
Note: This server currently supports password-based authentication, not OAuth2. A regular Google account password will not work; use an App Password if your account permits one. Google recommends OAuth-based sign-in, and managed accounts may disable app passwords.
Outlook.com and Exchange Online require OAuth2/Modern Authentication for IMAP and SMTP. This server currently accepts only a username and password, so Outlook/Hotmail accounts are not currently supported.
Outlook SMTP also uses STARTTLS on port 587, which would require SMTP_SECURE=false; changing that flag alone does not solve the OAuth requirement. See Microsoft's current IMAP and SMTP settings.
Security Notes
Authentication limitation: This server currently supports password or app-password authentication only, not OAuth2
Use app passwords where supported: Never use your primary account password when a provider offers a scoped app password
Require transport encryption: IMAP requires implicit TLS. SMTP uses implicit TLS when SMTP_SECURE=true and requires STARTTLS before authentication when it is false
Keep certificate verification enabled: Leave both TLS REJECT_UNAUTHORIZED settings at their default true unless you control and explicitly trust a private certificate authority
Protect stored credentials: MCP clients may save EMAIL_PASS in their local configuration. Restrict file permissions and never commit credentials to version control
Keep local env files private: .env and .env.* are ignored by Git; use a sanitized .env.example only when sharing configuration templates
Optional security integration: HOL Guard
HOL Guard is a separate local security layer for AI agents. Its community mcp.mail-server extension adds opt-in policy defaults for reviewing permanent email deletion. Guard is not required to run this server, and installing mcp-mail-server alone does not activate this coverage.
To use the integration:
Install Guard and configure its integration for your MCP client or agent. Check the harness support matrix; support and enforcement vary by client and event type.
Use a Guard release whose installed catalog includes mcp.mail-server, and have a local administrator explicitly enable this external, opt-in extension through Guard's local protection controls. A directory listing, publisher claim, or Cloud setting does not activate it locally.
Route the server's MCP tool calls through the supported Guard-managed proxy or hooks, and verify the effective local policy before relying on it. Calls made directly outside that protected path are not covered.
When the extension is active, its reviewed policy contributes these defaults:
delete_message and delete_messages: review, adding a user-approval checkpoint before permanent deletion.
list_mailboxes and search_messages: allow only when the reviewed npx launcher, STDIO transport, npm registry package selector, and source identity match, without package-manager overrides. A matching package name alone is insufficient.
Other tools: inherit, retaining host-policy handling rather than automatically allowing all email operations. In particular, get_message and get_messages are not treated as unconditionally read-only because markSeen can change message state.
Local custom grants and stronger Guard constraints retain their precedence. Guard does not make permanent deletion reversible or replace mailbox permissions and backups; this integration is not a security certification. See the upstream contribution PR for the implementation and regression coverage.
Development
Development and runtime require Node.js 22.13 or newer. The repository pins Node.js 22.23.0 LTS in .nvmrc for local development.
Clone the repository:
git clone https://github.com/yunfeizhu/mcp-mail-server.git
cd mcp-mail-server
Install dependencies:
npm install
Build the project:
npm run build
Run the complete local quality gate with:
npm run check
Use npm run format, npm run lint:fix, npm run format:check, and npm run lint for focused formatting and linting workflows.
Rollup resolves and transpiles src/*.ts directly into the single-file release bundle. Local TypeScript imports omit file extensions, while third-party package subpaths retain the extensions published by those packages. tsc performs type checking only and tests load source through tsx. Runtime libraries remain external and are installed from the package's declared dependencies.
The command builds the project and opens the version-pinned MCP Inspector 1.0.0 UI. In the connection pane, configure:
Transport Type: STDIO
Command: node
Arguments: dist/index.js
Environment Variables: the IMAP, SMTP, username, and password variables listed above
Click Connect, open Tools, and call check_connection to verify IMAP and SMTP before testing search, read, or send tools. Other tools auto-connect as needed. Attachment tools also require MAIL_ALLOWED_ROOTS.
The MCP server and the version-pinned Inspector both require Node.js 22.13 or newer.
Automated checks and npm publishing
GitHub Actions validates every branch push and pull request on Node.js 22 and 24, including formatting, lint, types, the release build, tests, release metadata, and npm package contents. Release Please prepares a release PR that synchronizes package/lockfile versions, both changelogs, and both README release summaries. Merge that PR when you decide to release; its version tag triggers fresh verification and npm OIDC publishing of the verified tarball.
Maintainers must enable Actions-created PRs and configure the npm trusted publisher once. See the release guide for setup, automatic release preparation, and retry instructions.
Release notes
Bug Fixes
preserve mail identities and bound styled replies (6b4977d)
Bug Fixes
Fix reply-subject normalization when Re, 回复, or 答复 is followed by a full-width colon (：) or whitespace before the colon. Subjects such as 回复：Hello, RE : Hello, and Re: 回复：RE : Hello now normalize to Hello, preventing stacked reply prefixes and missed matches when looking up sent threads. (#17, #16)
Added
move_messages and delete_messages handle up to 200 distinct UIDs from one mailbox per call, bringing the server to 14 tools.
save_attachment can select one attachment by exact attachmentFilename instead of attachmentIndex. Duplicate filenames require an index; omit both selectors to save all attachments.
Improved
Batch operations report success and failure counts plus per-UID results. A failed UID does not abort the remaining entries; inspect failed results before retrying.
Each batch operation reselects the source mailbox read-write and verifies the initial UIDVALIDITY before acting on a UID, even when the caller omits uidValidity. Destination references are refreshed after the move batch completes.
Documentation
Updated the English and Chinese tool references and made the Node.js 22.13.0 minimum explicit before client setup.
Fixed
Fetch each complete RFC822 message as one IMAP body stream so providers such as Gmail cannot reorder separately requested header and text sections, restoring headers, Message-ID, attachment metadata, and attachment downloads.
Fixed
Restore IMAP APPEND on Node.js 23 and newer by letting the mail server assign INTERNALDATE, avoiding the removed util.isDate API in [email protected].
Breaking changes
Replaced 25 overlapping tools with 12 focused tools, including unified search_messages, check_connection, find_unreplied_messages, and recurring-report continue_email_thread.
Removed implicit mailbox state and redundant connection, search, count, and attachment-metadata tools.
Fixed
Apply exact date ranges before result limits, preserve reply-all recipients, and determine reply state from thread headers.
Use targeted UID EXPUNGE so deleting one message cannot expunge other messages already marked \\Deleted.
Return lightweight search summaries by default and fetch full bodies only for selected results.
Return RFC822 message sizes when available (null otherwise) and structured, password-redacted diagnostics when saving a sent copy fails.
Reject missing UIDs before move/delete, bound header and batch memory, verify SMTP live, and enforce one candidate budget across every search path.
Keep runtime libraries as declared npm dependencies and reject undeclared external imports from the release bundle.
Added
Added move_message to move a mailbox-scoped message into an existing target mailbox.
Added optional plain-text and HTML signatures to send_email and reply_to_email.
Improved
Return the destination UID after a move when the IMAP server provides it, with a refresh hint otherwise.
Place reply signatures after the new content and before the quoted original while preserving MIME alternatives.
Validate move targets and reject moves into the current mailbox.
Documentation
Redesigned the README around common workflows, a shorter quick start, grouped tools, and clearer client configuration.
See CHANGELOG.md for the complete version history.
Star History
Contributing
Bug reports, feature ideas, and pull requests are welcome. Start with the issue tracker or open a pull request directly.
Belum ada daftar tool. Server remote mendapatkannya setelah pemeriksaan kesehatan pertama.
FAQ
Pertanyaan
Bagaimana cara menginstal MCP Mail Server?
Salin konfigurasi stdio untuk Cursor, Claude Desktop, Claude Code, atau VS Code di halaman ini. Konfigurasi ini memakai instalasi dari penerbit, bukan proxy PlugMCP.
Apakah MCP Mail Server memerlukan kunci API?
Tidak ada variabel lingkungan wajib yang tercantum di catatan ini.
Transport apa yang digunakan MCP Mail Server?
MCP Mail Server berjalan secara lokal melalui stdio.
Kapan MCP Mail Server terakhir diperiksa?
Terakhir diperiksa 2026-11-13. MCP server for IMAP/SMTP email access with environment-based configuration
