Mail MCP Server

English | 中文

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.)

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.0

Configuration

Configure via environment variables:

IMAP Settings

SMTP Settings

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-password

Note: For Gmail, you need to use an App Password.

Usage

As MCP Server

# Run as stdio MCP server
python -m mail_mcp.server

With npx (npm)

# Install and run
npx mail-mcp-server

MCP 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 messages
• UNSEEN - Unread messages
• SEEN - Read messages
• FLAGGED - Flagged messages
• FROM <email> - From specific sender
• TO <email> - To specific recipient
• SUBJECT <text> - Subject contains text
• SINCE <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 call

Common Content Types:

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 使用示例

详见 skills/mail-skill/SKILL.md

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 -v

Test 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.md

Error Handling

All tools return structured responses. Errors are returned as:

{
  "error": "Error message description"
}

SMTP errors include specific exception types:

• SMTPConnectionError - Connection failed
• SMTPAuthError - Authentication failed
• SMTPSendError - Send failed
• SMTPRecipientsError - Invalid recipients

Supported Email Providers

License

MIT