Mail MCP Server
Provides full email management capabilities for Gmail through IMAP and SMTP protocols, including folder operations, complex email searching, reading, and sending emails with attachments or OAuth2 authentication.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Mail MCP Server find unread emails from Sarah about the budget"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Mail MCP Server
Email management via MCP (Model Context Protocol). Provides complete IMAP email operations and SMTP sending capabilities through a standardized MCP interface.
Features
Folder Management: List, create, delete, rename email folders
Email Search: Search with complex IMAP criteria (FROM, TO, SUBJECT, UNSEEN, etc.)
Email Operations: Get full email details including body and attachments
Mark Operations: Mark as read/unread, flagged/unflagged
Move/Copy: Move or copy emails between folders
Delete: Delete emails with expunge
SMTP Sending: Send emails with attachments, replies, and forwards
SSL (465) and STARTTLS (587) support
Plain text / HTML dual format
File attachments
OAuth2 authentication (for Gmail, etc.)
Related MCP server: Email MCP Server
Installation
# Clone and install
cd mail-mcp-server
pip install -e .
# Or install directly
pip install mcp>=1.0.0 pydantic>=2.0.0 python-dotenv>=1.0.0Configuration
Configure via environment variables:
IMAP Settings
Variable | Description | Default |
| IMAP server hostname |
|
| IMAP server port |
|
| Email username | - |
| Email password | - |
| Use SSL connection |
|
SMTP Settings
Variable | Description | Default |
| SMTP server hostname |
|
| SMTP server port |
|
| Email username (same as IMAP) | - |
| Email password (same as IMAP) | - |
| Use SSL/TLS (port 465) |
|
| Use STARTTLS (port 587) |
|
Example
# IMAP (阿里云企业邮箱示例)
export IMAP_HOST=mail.qiye.aliyun.com
export IMAP_PORT=993
export EMAIL_USER=your.email@company.com
export EMAIL_PASSWORD=your-password
export IMAP_SSL=true
# SMTP (for sending)
export SMTP_HOST=smtp.qiye.aliyun.com
export SMTP_PORT=465
export SMTP_SSL=true
# Gmail 示例 (需要 App Password)
# export IMAP_HOST=imap.gmail.com
# export SMTP_HOST=smtp.gmail.com
# export EMAIL_PASSWORD=your-app-passwordNote: For Gmail, you need to use an App Password.
Usage
As MCP Server
# Run as stdio MCP server
python -m mail_mcp.serverWith npx (npm)
# Install and run
npx mail-mcp-serverMCP Tools
Folder Management
list_folders
List all email folders.
{
"name": "list_folders",
"arguments": {}
}create_folder
Create a new folder.
{
"name": "create_folder",
"arguments": {
"folder_name": "Work/Projects"
}
}delete_folder
Delete a folder.
{
"name": "delete_folder",
"arguments": {
"folder_name": "Work/Old"
}
}rename_folder
Rename a folder.
{
"name": "rename_folder",
"arguments": {
"old_name": "Work/Old",
"new_name": "Work/Archive"
}
}Email Operations
search_emails
Search emails with IMAP criteria.
{
"name": "search_emails",
"arguments": {
"folder": "INBOX",
"criteria": "UNSEEN FROM sender@example.com",
"limit": 10
}
}Common Criteria:
ALL- All messagesUNSEEN- Unread messagesSEEN- Read messagesFLAGGED- Flagged messagesFROM <email>- From specific senderTO <email>- To specific recipientSUBJECT <text>- Subject contains textSINCE <date>- After date (e.g., "14-Mar-2024")BEFORE <date>- Before date
get_email
Get detailed email information.
{
"name": "get_email",
"arguments": {
"folder": "INBOX",
"message_id": "1",
"uid": "100",
"include_body": true
}
}Note: Provide either message_id or uid.
Mark Operations
mark_read
Mark email as read (seen).
{
"name": "mark_read",
"arguments": {
"folder": "INBOX",
"message_id": "1"
}
}mark_unread
Mark email as unread.
{
"name": "mark_unread",
"arguments": {
"folder": "INBOX",
"uid": "100"
}
}mark_flagged
Mark email as flagged (starred).
{
"name": "mark_flagged",
"arguments": {
"folder": "INBOX",
"message_id": "1"
}
}unmark_flagged
Remove flagged status.
{
"name": "unmark_flagged",
"arguments": {
"folder": "INBOX",
"message_id": "1"
}
}Move/Copy Operations
move_email
Move email to another folder.
{
"name": "move_email",
"arguments": {
"source_folder": "INBOX",
"target_folder": "Archive",
"message_id": "1"
}
}copy_email
Copy email to another folder.
{
"name": "copy_email",
"arguments": {
"source_folder": "INBOX",
"target_folder": "Archive",
"uid": "100"
}
}Delete
delete_email
Delete email (marks as Deleted and expunges).
{
"name": "delete_email",
"arguments": {
"folder": "INBOX",
"message_id": "1"
}
}SMTP Sending
send_email
Send an email with optional HTML body and attachments.
{
"name": "send_email",
"arguments": {
"to": ["recipient@example.com"],
"subject": "Email Subject",
"body_text": "Plain text body",
"body_html": "<p>HTML body</p>",
"cc": ["cc@example.com"],
"bcc": ["bcc@example.com"],
"attachments": [
{
"filename": "document.pdf",
"content_type": "application/pdf",
"data_base64": "JVBERi0xLjQK..."
}
]
}
}Sending Attachments:
Encode file content as base64:
import base64
with open("report.zip", "rb") as f:
data_base64 = base64.b64encode(f.read()).decode()
# Then use in MCP callCommon Content Types:
File Type | Content Type |
| |
ZIP |
|
Excel |
|
Word |
|
Image (PNG) |
|
Image (JPEG) |
|
Text |
|
send_reply
Reply to an email.
{
"name": "send_reply",
"arguments": {
"to": ["recipient@example.com"],
"subject": "Re: Original Subject",
"body_text": "Reply text",
"reply_to_message_id": "<original@example.com>",
"quote_original": true
}
}send_forward
Forward an email to another recipient.
{
"name": "send_forward",
"arguments": {
"to": ["forward@example.com"],
"subject": "Fwd: Original Subject",
"original_folder": "INBOX",
"original_message_id": "1",
"body_text": "Here is the forwarded email:"
}
}Utilities
get_current_date
Get current date and time.
{
"name": "get_current_date",
"arguments": {}
}Skills
项目包含一个 OpenClaw skill,帮助用户更好地使用邮件服务。
安装 Skill
# 复制到 OpenClaw skills 目录
cp -r skills/mail-skill ~/.openclaw/skills/Skill 功能
自动检查 mail-mcp 是否已安装
提供常见邮箱配置示例
mcporter 使用示例
Testing
# Install test dependencies
pip install -e ".[dev]"
# Run all tests
pytest tests/ -v
# Run integration tests only
pytest tests/integration/ -v
# Run SMTP tests
pytest tests/integration/test_smtp_server.py -vTest Status:
SMTP Tests: 21 passed ✅
IMAP Integration: 17 passed ✅
Unit Tests: 64 passed (some mock issues in legacy tests)
Project Structure
mail-mcp-server/
├── src/
│ └── mail_mcp/
│ ├── __init__.py
│ ├── __main__.py
│ ├── server.py # MCP server & IMAP client
│ └── smtp/ # SMTP module
│ ├── __init__.py # Exports & Attachment class
│ ├── connection.py # SMTP connection management
│ ├── auth.py # Authentication (PLAIN/LOGIN/OAuth2)
│ ├── errors.py # Custom exceptions
│ └── operations/
│ ├── __init__.py
│ ├── message.py # Email message building
│ └── send.py # send_email/reply/forward
├── tests/
│ ├── integration/
│ │ ├── test_server.py # IMAP integration tests
│ │ └── test_smtp_server.py # SMTP integration tests
│ └── unit/
│ ├── test_smtp.py # SMTP unit tests
│ └── ...
├── specs/
│ └── smtp-spec.md # SMTP specification
├── pyproject.toml
└── README.mdError Handling
All tools return structured responses. Errors are returned as:
{
"error": "Error message description"
}SMTP errors include specific exception types:
SMTPConnectionError- Connection failedSMTPAuthError- Authentication failedSMTPSendError- Send failedSMTPRecipientsError- Invalid recipients
Supported Email Providers
Provider | IMAP Host | SMTP Host | Notes |
Gmail |
|
| Requires App Password |
Outlook |
|
| |
阿里云企业邮箱 |
|
| |
腾讯企业邮箱 |
|
| |
QQ 邮箱 |
|
| Requires authorization code |
License
MIT
Available Tools
17 toolscopy_emailC
Copy email to another folder
Inputs: source_folder (required), target_folder (required), message_id, uid.
create_folderC
Create a new email folder
Inputs: folder_name (required).
delete_emailB
Delete email (mark as deleted and expunge)
Inputs: folder, message_id, uid.
delete_folderC
Delete an email folder
Inputs: folder_name (required).
get_current_dateA
Get current date and time
Inputs: no named parameters.
get_emailC
Get detailed email information
Inputs: folder, message_id, uid, include_body.
list_foldersB
List all email folders
Inputs: no named parameters.
mark_flaggedC
Mark email as flagged (starred)
Inputs: folder, message_id, uid.
mark_readC
Mark email as read (seen)
Inputs: folder, message_id, uid.
mark_unreadB
Mark email as unread (remove seen flag)
Inputs: folder, message_id, uid.
move_emailC
Move email to another folder
Inputs: source_folder (required), target_folder (required), message_id, uid.
rename_folderC
Rename an email folder
Inputs: old_name (required), new_name (required).
search_emailsC
Search emails with criteria
Inputs: folder, criteria, limit.
send_emailC
Send an email with optional HTML body and attachments
Inputs: to (required), subject (required), body_text, body_html, +3 more.
send_forwardC
Forward an email to another recipient
Inputs: to (required), subject (required), original_folder, original_message_id, +2 more.
send_replyC
Reply to an email
Inputs: to (required), subject (required), reply_to_message_id (required), body_text, +2 more.
unmark_flaggedA
Unmark email as flagged (remove starred)
Inputs: folder, message_id, uid.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Each tool has a clearly distinct purpose with no ambiguity. For example, copy_email and move_email handle different operations on emails, while mark_read and mark_unread are complementary but distinct actions. The descriptions clearly differentiate all tools, making misselection unlikely.
Tool names follow a consistent verb_noun pattern throughout, using snake_case uniformly. Examples include copy_email, create_folder, delete_email, and search_emails. This predictability aids in understanding and using the toolset effectively.
With 17 tools, the count is slightly high but reasonable for an email management server, covering a comprehensive range of operations. It includes core email actions, folder management, and status updates, though it may feel slightly heavy compared to more minimal implementations.
The toolset provides complete coverage for email management, including CRUD operations for emails and folders, lifecycle actions like sending and replying, and status management (read/unread, flagged/unflagged). No obvious gaps exist, ensuring agents can handle typical workflows without dead ends.
Maintenance
Related MCP Connectors
An MCP server that provides email capabilities, hosted on Alpic platform
An MCP server that provides email capabilities, hosted on Alpic platform
An MCP server that provides email capabilities, hosted on Alpic platform
Hosted MCP server for your Gmail, Outlook and IMAP mail, with mailboxes and scopes set per agent.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA comprehensive MCP server for unified email management that supports both Gmail and IMAP accounts via a single interface. It enables users to search across multiple accounts, list, read, send, and archive emails with integrated health monitoring and secure authentication.1MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI models to read, search, and send emails via IMAP and SMTP protocols. It supports various providers like Gmail and Outlook, allowing for tasks such as retrieving unread messages, searching by sender, and managing mailbox folders.-
- FlicenseBqualityNot gradedmaintenanceThis MCP server enables users to manage emails via POP3 and SMTP protocols, allowing for listing, searching, reading, and sending messages. It also supports fetching email threads and extracting text content from various document attachments including PDFs and Office files.8-
- AlicenseAqualityCmaintenanceAn MCP server providing comprehensive email capabilities via IMAP and SMTP, enabling AI assistants to read, search, send, manage, schedule, and analyze emails across multiple accounts.52905 npm156LGPL 3.0