Mail Server

БесплатноHosted

An MCP server providing comprehensive email management through IMAP and SMTP, allowing users to search, read, and organize messages. It supports advanced featur

автор: AdJIa

GitHub

Описание

An MCP server providing comprehensive email management through IMAP and SMTP, allowing users to search, read, and organize messages. It supports advanced features like folder manipulation, sending emails with attachments, and secure authentication for various email providers.

README

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

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 protected]
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 [email protected]",
    "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": ["[email protected]"],
    "subject": "Email Subject",
    "body_text": "Plain text body",
    "body_html": "<p>HTML body</p>",
    "cc": ["[email protected]"],
    "bcc": ["[email protected]"],
    "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": ["[email protected]"],
    "subject": "Re: Original Subject",
    "body_text": "Reply text",
    "reply_to_message_id": "<[email protected]>",
    "quote_original": true
  }
}

`send_forward`

Forward an email to another recipient.

{
  "name": "send_forward",
  "arguments": {
    "to": ["[email protected]"],
    "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

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

Как установить

Добавь это в claude_desktop_config.json и перезапусти Claude Desktop.

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

Command Palette

Mail Server

Описание

README

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