Mail MCP Server

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`

Dele