mail-mcp

mail-mcp is a production-ready email MCP server for AI agents, written in Rust, supporting IMAP, SMTP, Exchange Web Services (EWS), and the Microsoft Graph API, with real OAuth2, multi-account, and multi-provider support. Most email MCP servers only support IMAP reading, whereas this project covers reading, searching, sending, replying, forwarding, batch operations, the Microsoft Graph API, and Exchange Web Services, among other capabilities.

1. Main purpose This project is used to let AI agents operate email through the MCP protocol: reading, searching, sending, replying, forwarding, batch processing, and downloading attachments. Its design goals include multi-account management, multi-provider compatibility (such as Microsoft 365, Hotmail, Gmail, Zoho, iCloud, NetEase 126/163/yeah.net, etc.), and more secure OAuth2 authentication.

2. Main capabilities

3. Email operations: reading, searching, sending, replying, forwarding, and batch operations.

4. Attachment handling: the newly added imap_get_attachment tool can download a single attachment to disk and returns the file path, file name, content type, part_id, and size; binary content does not enter the model response, avoiding context bloat. The optional include_base64 attaches base64 when the attachment does not exceed max_inline_bytes (default 256 KiB).

5. Search enhancements: imap_search_all_mailboxes can perform one search in every selectable mailbox in the account and return the latest matching results, with each result marked with the mailbox it belongs to, which is suitable for providers without an "All Mail" folder (such as iCloud); the concurrency is controlled by MAIL_IMAP_SEARCH_CONCURRENCY (default 4, range 1..=8), and a failure in a single mailbox is reported without aborting the search. imap_search_messages adds a thread_message_id condition, which can match an email and all emails carrying that ID in their In-Reply-To or References, making it convenient to fetch an entire conversation.

6. Folder management: imap_list_mailboxes has an upper limit on the number of mailboxes configured by MAIL_IMAP_MAX_MAILBOXES (default 200, range 1..=10000), and the response adds total and truncated fields, making it easier to determine whether the list was truncated. It supports iCloud mailbox alias resolution, such as Sent → Sent Messages, [Gmail]/Sent Mail, Trash → Deleted Messages, etc., for search, copy, and move operations.

7. Read status: raw email retrieval uses BODY.PEEK[], so reading email no longer sets \Seen; for servers that reject PEEK, it falls back to BODY[].

8. Sent mail archiving: SAVE_SENT supports per-account configuration and provides provider-aware defaults. Gmail and Zoho do not append again when saved server-side; when Office 365 or generic SMTP does not automatically save, MCP appends. The priority is: per-account override → global configuration → provider default.

9. Send validation: v0.4.6 introduces server-side validation; if body_text or body_html contains tool-call wrapper syntax (such as <body_text>, <function_calls>, <invoke name=, etc.), the tool call will be rejected before SMTP/Graph/EWS attempts.

10. Other fixes: graph_send_message no longer silently drops attachments when replying with attachments; inline for less than 3 MB, chunked upload session for 3 MB or more; NetEase servers send an RFC 2971 ID command after authentication for compatibility; MAIL_SMTP_<ID>_FROM_EMAIL can override the sender address for a shared/group mailbox.

11. Usage stdio transport is used by default. Setting MAIL_MCP_TRANSPORT=http switches to stateless streamable HTTP, by default bound to the /mcp path at 127.0.0.1:8000, configurable via MAIL_MCP_HTTP_HOST, MAIL_MCP_HTTP_PORT, MAIL_MCP_HTTP_PATH, and supporting graceful shutdown on SIGINT/SIGTERM. The HTTP endpoint itself has no built-in authentication, so it should remain on a loopback address or be placedBehind an authentication gateway. The attachment download directory can be determined via the output_dir parameter, the MAIL_ATTACHMENT_DOWNLOAD_DIR environment variable, or the system temporary directory; file names are sanitized and prefixed with a UID and part id to prevent conflicts. MAIL_ATTACHMENT_UPLOAD_DIR can restrict the scope of outbound file_path attachments. The project provides a Dockerfile and docker-compose, uses a scratch runtime image of about 16.9 MB, and supports amd64/arm64. The toolchain requires Rust 1.90 (the codebase's let-chains require >= 1.88).

IV. Applicable Scenarios Suitable for scenarios that require AI agents to perform email reading, searching, sending, replying, forwarding, batch operations, and attachment downloads across multiple email accounts and providers, especially integration environments that require OAuth2, multiple accounts, Microsoft Graph, or EWS support.

V. Limitations and Missing Information The HTTP transport endpoint has no built-in authentication. The attachment outbound scope restriction is optional to enable; when not set, behavior remains unchanged. Information on specific installation commands, authorization configuration steps, charging methods or prices, or platform support details is not yet provided in the materials.