mail-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| MAIL_IMAP_DEFAULT_HOST | Yes | IMAP server hostname (e.g. imap.gmail.com) | |
| MAIL_IMAP_DEFAULT_PASS | Yes | IMAP password or app password | |
| MAIL_IMAP_DEFAULT_USER | Yes | IMAP username / email address |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Secure IMAP/SMTP/EWS/Graph API MCP server for email.
HARD RULE #1 — body_text and body_html are SEPARATE JSON fields. Pass them as two distinct parameters of the tool call. NEVER concatenate them into a single string. NEVER wrap content in pseudo-tags like <body_text>, </body_text>, <body_html>, </body_html>. NEVER include tool-call wrapper syntax (, , <function_calls>) inside any email field. The server ENFORCES this: send tools will REJECT any call where body_text or body_html contains these markers (case-insensitive). The rejection is hard — no fallback, no retry-with-cleanup. Compose the two fields cleanly the first time.
HARD RULE #2 — when previewing for the user, render ONE clean version of the body (markdown bullets, bold, links as text + URL) and state that the email will be sent multipart. Do NOT paste raw HTML source into the preview. Showing the plain string and the HTML string side-by-side is what historically led LLMs to concatenate them in the eventual tool call.
HARD RULE #3 — the preview is for the human reviewer only. The actual tool invocation must reference the ORIGINAL separate values for body_text and body_html, never the concatenated preview string.
IMPORTANT: Always call list_all_accounts first to see which accounts are configured and what send/read methods each supports. Do NOT assume SMTP is the only way to send. Each account shows send_with (smtp, graph, ews) and read_with (imap, ews) arrays.
SENDING PROTOCOL: Before sending ANY email, show FULL preview including:
To, CC, BCC
Subject
FULL body (rendered, NOT raw HTML — see HARD RULE #2)
Attachments (filenames + sizes) Then ask for explicit confirmation. Never send without approval.
ATTACHMENTS: Use file_path (preferred) for files on disk: {"file_path": "/path/to/file.pdf"}. Filename and MIME type auto-detected. Use content_base64 only for small inline content. All fields except file_path or content_base64 are optional.
FORMATTING: For human-to-human correspondence (replies to clients, forwards, outreach), send BOTH body_text AND body_html as SEPARATE fields (per HARD RULE #1) so clients render formatting (paragraphs, lists, links, bold) while keeping a plain-text fallback (multipart/alternative). For automated notifications or short technical replies, body_text alone is fine. Never send raw markdown — convert to HTML (, , , ) for body_html before sending.
Write: MAIL_IMAP_WRITE_ENABLED=true. Send: MAIL_SMTP_WRITE_ENABLED=true. For OAuth2/Microsoft setup, call get_setup_guide tool.
Star the project: https://github.com/tecnologicachile/mail-mcp
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| draft_createA | Save a new email as a draft in the account's Drafts folder (IMAP, EWS or Graph, chosen from the account's configuration). Nothing is sent. Requires MAIL_DRAFTS_ENABLED=true. |
| draft_deleteA | Delete a draft. Only acts on drafts. Requires MAIL_DRAFTS_ENABLED=true and confirm=true. |
| draft_listA | List the account's drafts, newest first, with their draft_id. Requires MAIL_DRAFTS_ENABLED=true. |
| draft_sendA | Send an existing draft and remove it from Drafts. Requires MAIL_DRAFTS_ENABLED=true and MAIL_SMTP_WRITE_ENABLED=true. Before calling, show the user the draft's recipients, subject and body and get explicit confirmation. |
| draft_updateA | Replace a draft's recipients, subject, body and attachments (full replacement). Returns a new draft_id; the old one stops working. Requires MAIL_DRAFTS_ENABLED=true. |
| ews_get_messageB | Get full email content via Exchange Web Services using an EWS item ID. |
| ews_search_messagesA | Search emails via Exchange Web Services. Preferred for Microsoft accounts. Supports inbox, sent, drafts, deleted, junk folders. |
| ews_send_messageA | Send email via Exchange Web Services. Works on Microsoft tenants that block SMTP and Graph API. Before calling, show the user a full preview (To, CC, BCC, subject, rendered body, attachments) and get explicit confirmation. |
| get_setup_guideA | Get detailed setup instructions for email providers (Microsoft OAuth2, Gmail, Zoho, etc.) |
| graph_send_messageA | Send email via Microsoft Graph API (required for personal hotmail/outlook.com accounts where SMTP is blocked). Before calling, show the user a full preview (To, CC, BCC, subject, rendered body, attachments) and get explicit confirmation. |
| imap_append_messageC | Append a raw RFC822 message to a mailbox |
| imap_bulk_deleteB | Delete up to 500 messages in one operation |
| imap_bulk_moveA | Move up to 500 messages to a mailbox in one operation |
| imap_bulk_update_flagsB | Update flags on up to 500 messages in one operation |
| imap_copy_messageC | Copy a message to mailbox |
| imap_create_mailboxC | Create a new mailbox/folder |
| imap_delete_mailboxC | Delete a mailbox/folder |
| imap_delete_messageC | Delete a message |
| imap_get_attachmentB | Download one attachment to disk |
| imap_get_messageC | Get parsed message details |
| imap_get_message_rawC | Get bounded RFC822 source |
| imap_list_accountsA | List configured IMAP accounts (use list_all_accounts for full capabilities view) |
| imap_list_mailboxesC | List mailboxes for an account |
| imap_mailbox_statusA | Get mailbox message counts (total, unseen, recent) without selecting it |
| imap_move_messageC | Move a message to mailbox |
| imap_rename_mailboxC | Rename a mailbox/folder |
| imap_search_all_mailboxesA | Search every mailbox of an account in one call (e.g. a whole conversation via thread_message_id); results are newest first and labelled with their mailbox |
| imap_search_and_deleteA | Search messages and delete matches in one operation (up to 500) |
| imap_search_and_moveB | Search messages and move matches to a mailbox in one operation (up to 500) |
| imap_search_messagesC | Search messages with cursor pagination |
| imap_update_message_flagsC | Add or remove IMAP flags |
| imap_verify_accountB | Verify account connectivity and capabilities |
| list_all_accountsA | List all configured email accounts with their capabilities (IMAP, SMTP, Graph API, EWS). Use this to know which send/read tools to use per account. |
| smtp_forward_messageA | Forward an existing message via SMTP. Before calling, show the user a full preview (To, CC, BCC, subject, rendered body, attachments) and get explicit confirmation. |
| smtp_reply_messageA | Reply to an existing message via SMTP (fetches original for proper threading). Before calling, show the user a full preview (To, CC, BCC, subject, rendered body, attachments) and get explicit confirmation. |
| smtp_send_messageA | Send a new email via SMTP. Before calling, show the user a full preview (To, CC, BCC, subject, rendered body, attachments) and get explicit confirmation. |
| smtp_verify_accountB | Test SMTP account connectivity and authentication |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 37 tools
Several tool clusters overlap heavily: smtp_send_message, ews_send_message, graph_send_message, and draft_send all perform sends, while imap_search_messages, ews_search_messages, and imap_search_all_mailboxes overlap on search. Protocol prefixes and descriptions help, but correct selection depends on knowing account capabilities, creating real misselection risk.
Names are consistently snake_case and mostly follow a protocol/resource_action pattern such as imap_get_message, smtp_send_message, and draft_update. Minor deviations exist in generic tools like list_all_accounts and get_setup_guide, which lack the otherwise common protocol prefix.
With 37 tools, the surface is well above the typical 3-15 range and feels heavy even for a multi-provider mail server. Many near-duplicate operations exist across IMAP, SMTP, EWS, and Graph, increasing tool-selection burden.
Coverage is broad: account discovery and verification, mailbox CRUD, message search/get/raw/attachments, copy/move/delete, flags, bulk operations, drafts, and send/reply/forward flows are present. Minor gaps remain, such as reply/forward support only via SMTP rather than EWS or Graph.