Which integrations are available for this 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.

How do I use Mail MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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

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

Mail MCP Server

Features

Installation

Configuration

IMAP Settings

SMTP Settings

Example

Usage

As MCP Server

With npx (npm)

MCP Tools

Folder Management

list_folders

create_folder

delete_folder

rename_folder

Email Operations

search_emails

get_email

Mark Operations

mark_read

mark_unread

mark_flagged

unmark_flagged