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

Variable	Description	Default
IMAP_HOST	IMAP server hostname	imap.example.com
IMAP_PORT	IMAP server port	993
EMAIL_USER	Email username	-
EMAIL_PASSWORD	Email password	-
IMAP_SSL	Use SSL connection	true

SMTP Settings

Variable	Description	Default
SMTP_HOST	SMTP server hostname	smtp.example.com
SMTP_PORT	SMTP server port	465
EMAIL_USER	Email username (same as IMAP)	-
EMAIL_PASSWORD	Email password (same as IMAP)	-
SMTP_SSL	Use SSL/TLS (port 465)	true
SMTP_STARTTLS	Use STARTTLS (port 587)	false

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 imap_mcp.server

With npx (npm)

# Install and run
npx imap-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:

File Type	Content Type
PDF	application/pdf
ZIP	application/zip
Excel	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Word	application/vnd.openxmlformats-officedocument.wordprocessingml.document
Image (PNG)	image/png
Image (JPEG)	image/jpeg
Text	text/plain

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

imap-mcp-server/
├── src/
│   └── imap_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

Provider	IMAP Host	SMTP Host	Notes
Gmail	imap.gmail.com	smtp.gmail.com	Requires App Password
Outlook	outlook.office365.com	smtp.office365.com
阿里云企业邮箱	mail.qiye.aliyun.com	smtp.qiye.aliyun.com
腾讯企业邮箱	imap.exmail.qq.com	smtp.exmail.qq.com
QQ 邮箱	imap.qq.com	smtp.qq.com	Requires authorization code

License

MIT