MCP Servers

A collection of Model Context Protocol servers, templates, tools and more.

M
Mail MCP Server
by @AdJIa
GitHub Repo(1 stars)

IMAP MCP Server - Email management via MCP protocol with SMTP sending

Created 3/14/2026
Updated about 7 hours ago
README
View Source
Repository documentation and setup instructions

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

Quick Setup
Installation guide for this server

Install Package (if required)

uvx mail-mcp-server

Cursor configuration (mcp.json)

{ "mcpServers": { "adjia-mail-mcp-server": { "command": "uvx", "args": [ "mail-mcp-server" ] } } }