mail-mcp

mail-mcp

Production-ready email MCP server for AI agents
IMAP + SMTP + EWS + Microsoft Graph API — built in Rust

---

Most email MCP servers only do IMAP reads. This one does everything: read, search, send, reply, forward, bulk operations, Microsoft Graph API, and Exchange Web Services — with real OAuth2, multi-account, and multi-provider support. Written in Rust for speed and safety.

Why This Project

	mail-mcp	Typical email MCP
IMAP read/write	18 tools	3-5 tools
SMTP send/reply/forward	Yes	No or broken
Microsoft Graph API	Yes	No
EWS (Exchange Web Services)	Yes	No
OAuth2 (XOAUTH2)	Native	No
Multi-account	Yes	Single account
Microsoft 365 + Hotmail	Both work	Usually neither
Language	Rust (fast, safe)	TypeScript/Python
Tests	47 unit + integration	Mocks only

Feature Matrix

Provider	IMAP	SMTP	Graph API	EWS	OAuth2	Multi-account
Microsoft 365 (enterprise)	Yes	Admin-dependent	Yes	Yes	Yes	Yes
Hotmail / Outlook.com	Yes	Blocked by MS	Yes	Yes	Yes	Yes
Gmail	Yes	Yes	—	—	Yes	Yes
Zoho	Yes	Yes	—	—	—	Yes
Fastmail	Yes	Yes	—	—	—	Yes
Any IMAP/SMTP server	Yes	Yes	—	—	—	Yes

EWS is the simplest way to add Microsoft accounts — single OAuth2 token for both reading and sending. Works even on tenants that block Graph API and IMAP.

Quickstart — Let Claude Code do it

Copy and paste this prompt into Claude Code and it will install, compile, and configure everything for you:

Install and configure the mail-mcp MCP server from https://github.com/tecnologicachile/mail-mcp

1. Clone the repo, build with cargo build --release
2. Add the MCP server to .claude.json with the binary path
3. For Microsoft accounts: use EWS (simplest) — run device code flow with
   client_id d3590ed6-52b3-4102-aeff-aad2292ab01c and scope
   https://outlook.office365.com/EWS.AccessAsUser.All offline_access
   Then configure MAIL_EWS_<ID>_USER and MAIL_EWS_<ID>_REFRESH_TOKEN
4. For Gmail: configure MAIL_IMAP + MAIL_SMTP with App Password from
   https://myaccount.google.com/apppasswords
5. For Zoho: configure MAIL_IMAP + MAIL_SMTP with standard password
6. Enable write/send: MAIL_IMAP_WRITE_ENABLED=true, MAIL_SMTP_WRITE_ENABLED=true

My email accounts to configure:
- <your-email@example.com>

Replace the last line with your email(s). Claude Code will guide you through each step including the OAuth2 device code flow for Microsoft accounts.

Manual Setup (2 minutes)

git clone https://github.com/tecnologicachile/mail-mcp.git
cd mail-mcp
cargo build --release

Add to your MCP client config (Claude Code, Cursor, etc.):

{
  "mcpServers": {
    "mail": {
      "command": "./target/release/mail-mcp",
      "env": {
        "MAIL_IMAP_DEFAULT_HOST": "imap.gmail.com",
        "MAIL_IMAP_DEFAULT_USER": "you@gmail.com",
        "MAIL_IMAP_DEFAULT_PASS": "your-app-password",
        "MAIL_SMTP_DEFAULT_HOST": "smtp.gmail.com",
        "MAIL_SMTP_DEFAULT_PORT": "587",
        "MAIL_SMTP_DEFAULT_USER": "you@gmail.com",
        "MAIL_SMTP_DEFAULT_PASS": "your-app-password",
        "MAIL_SMTP_DEFAULT_SECURE": "starttls",
        "MAIL_IMAP_WRITE_ENABLED": "true",
        "MAIL_SMTP_WRITE_ENABLED": "true"
      }
    }
  }
}

That's it. Your AI agent can now read, search, send, reply, and manage emails.

Microsoft Account? Use Graph API

Microsoft blocks SMTP on personal accounts. Use Graph API instead:

{
  "env": {
    "MAIL_IMAP_DEFAULT_HOST": "outlook.office365.com",
    "MAIL_IMAP_DEFAULT_USER": "you@hotmail.com",
    "MAIL_IMAP_DEFAULT_PASS": "your-app-password",
    "MAIL_OAUTH2_DEFAULT_PROVIDER": "microsoft",
    "MAIL_OAUTH2_DEFAULT_CLIENT_ID": "9e5f94bc-e8a4-4e73-b8be-63364c29d753",
    "MAIL_OAUTH2_DEFAULT_CLIENT_SECRET": "none",
    "MAIL_OAUTH2_DEFAULT_REFRESH_TOKEN": "<your-token>"
  }
}

Get your token in 1 minute with device code flow. See Account Setup Guide.

30 MCP Tools

Read (8 tools)

Tool	What it does
list_all_accounts	List all accounts with capabilities (IMAP, SMTP, Graph, EWS)
imap_list_accounts	List IMAP accounts
imap_verify_account	Test connectivity and auth
imap_list_mailboxes	List folders
imap_mailbox_status	Message counts
imap_search_messages	Search with cursor pagination
imap_get_message	Parsed message (text, HTML, attachments)
imap_get_message_raw	RFC822 source

Write (11 tools)

Tool	What it does
imap_update_message_flags	Add/remove flags
imap_copy_message	Copy (cross-account supported)
imap_move_message	Move to folder
imap_delete_message	Delete with confirmation
imap_create_mailbox	Create folder
imap_delete_mailbox	Delete folder
imap_rename_mailbox	Rename folder
imap_append_message	Append raw message
imap_bulk_move	Move up to 500 at once
imap_bulk_delete	Delete up to 500 at once
imap_bulk_update_flags	Flag up to 500 at once

Send (5 tools)

Tool	What it does
smtp_send_message	Send email (text/HTML, CC/BCC)
smtp_reply_message	Reply with threading headers
smtp_forward_message	Forward with original inline
smtp_verify_account	Test SMTP connectivity
graph_send_message	Send via Microsoft Graph API (with reply threading)

EWS — Exchange Web Services (3 tools)

Tool	What it does
ews_search_messages	Search emails via EWS (inbox, sent, drafts, etc.)
ews_get_message	Get full email content via EWS
ews_send_message	Send email via EWS

Attachments

Send files with any send tool. Two modes:

// Large files — MCP reads from disk (recommended)
"attachments": [{"file_path": "/path/to/report.pdf"}]

// Small files — inline base64
"attachments": [{"filename": "note.txt", "content_type": "text/plain", "content_base64": "SGVsbG8="}]

Filename and MIME type are auto-detected from the file path. Reply with include_original_attachments: true to forward original attachments.

Bulk Operations (2 tools)

Tool	What it does
imap_search_and_move	Search + move matches
imap_search_and_delete	Search + delete matches

Multi-Account

Configure as many accounts as you need:

# Gmail
MAIL_IMAP_GMAIL_HOST=imap.gmail.com
MAIL_IMAP_GMAIL_USER=me@gmail.com
MAIL_IMAP_GMAIL_PASS=app-password

# Microsoft 365
MAIL_IMAP_WORK_HOST=outlook.office365.com
MAIL_IMAP_WORK_USER=me@company.com
MAIL_OAUTH2_WORK_PROVIDER=microsoft
MAIL_OAUTH2_WORK_CLIENT_ID=your-client-id
MAIL_OAUTH2_WORK_CLIENT_SECRET=none
MAIL_OAUTH2_WORK_REFRESH_TOKEN=your-token

# Zoho
MAIL_IMAP_DEFAULT_HOST=imap.zoho.com
MAIL_IMAP_DEFAULT_USER=info@mydomain.com
MAIL_IMAP_DEFAULT_PASS=password
MAIL_SMTP_DEFAULT_HOST=smtp.zoho.com
MAIL_SMTP_DEFAULT_USER=info@mydomain.com
MAIL_SMTP_DEFAULT_PASS=password
MAIL_SMTP_DEFAULT_SECURE=starttls

Use account_id in tool calls: "account_id": "gmail", "account_id": "work", "account_id": "default".

Security

• TLS enforced on all connections (except localhost proxies)
• Passwords in SecretString — never logged or returned in responses
• Write operations gated — require explicit MAIL_IMAP_WRITE_ENABLED=true
• Send operations gated — require explicit MAIL_SMTP_WRITE_ENABLED=true
• Delete confirmation — requires confirm: true
• HTML sanitized with ammonia (prevents XSS)
• Bounded outputs — body text, HTML, attachments truncated to configurable limits
• OAuth2 tokens cached with 10-minute refresh margin
• No secrets in responses — credentials never exposed via MCP tools

Configuration Reference

Full environment variable reference

IMAP (per account)

Variable	Required	Default	Description
MAIL_IMAP_<ID>_HOST	Yes	—	IMAP server
MAIL_IMAP_<ID>_PORT	No	993	IMAP port
MAIL_IMAP_<ID>_USER	Yes	—	Username
MAIL_IMAP_<ID>_PASS	Yes*	—	Password (*optional with OAuth2)
MAIL_IMAP_<ID>_SECURE	No	true	Use TLS

SMTP (per account)

Variable	Required	Default	Description
MAIL_SMTP_<ID>_HOST	Yes	—	SMTP server
MAIL_SMTP_<ID>_PORT	No	587	SMTP port
MAIL_SMTP_<ID>_USER	Yes	—	Username
MAIL_SMTP_<ID>_PASS	No	—	Password (optional with OAuth2)
MAIL_SMTP_<ID>_SECURE	No	starttls	starttls, tls, or plain

OAuth2 (per account)

Variable	Required	Default	Description
MAIL_OAUTH2_<ID>_PROVIDER	Yes	—	google or microsoft
MAIL_OAUTH2_<ID>_CLIENT_ID	Yes	—	OAuth2 client ID
MAIL_OAUTH2_<ID>_CLIENT_SECRET	Yes	—	Client secret (`no

---

README truncated. View full README on GitHub.