Mail MCP Server

邮件MCP服务器

英语 | 中文

通过MCP（模型上下文协议）进行电子邮件管理。通过标准化的MCP接口提供完整的IMAP电子邮件操作和SMTP发送功能。

特性

• 文件夹管理：列出、创建、删除、重命名电子邮件文件夹
• 电子邮件搜索：使用复杂的IMAP条件进行搜索（发件人、收件人、主题、未筛选等）
• 电子邮件操作：获取完整的电子邮件详细信息，包括正文和附件
• 标记操作：标记为已读/未读、标记/未标记
• 移动/复制：在文件夹之间移动或复制电子邮件
• 删除：使用删除功能删除电子邮件
• SMTP发送：发送带有附件、回复和转发的电子邮件

- SSL（465）和STARTTLS（587）支持 - 纯文本/HTML双格式 - 文件附件 - OAuth2身份验证（适用于Gmail等）

安装

# 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

配置

通过环境变量进行配置：

IMAP设置

SMTP设置

示例

# 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

备注：对于Gmail，您需要使用 应用程序密码.

用法

作为MCP服务器

# Run as stdio MCP server
python -m mail_mcp.server

使用npx（npm）

# Install and run
npx mail-mcp-server

MCP工具

文件夹管理

list_folders

列出所有电子邮件文件夹。

{
  "name": "list_folders",
  "arguments": {}
}

create_folder

创建一个新文件夹。

{
  "name": "create_folder",
  "arguments": {
    "folder_name": "Work/Projects"
  }
}

delete_folder

删除文件夹。

{
  "name": "delete_folder",
  "arguments": {
    "folder_name": "Work/Old"
  }
}

rename_folder

重命名文件夹。

{
  "name": "rename_folder",
  "arguments": {
    "old_name": "Work/Old",
    "new_name": "Work/Archive"
  }
}

电子邮件操作

search_emails

使用IMAP条件搜索电子邮件。

{
  "name": "search_emails",
  "arguments": {
    "folder": "INBOX",
    "criteria": "UNSEEN FROM sender@example.com",
    "limit": 10
  }
}

通用标准：

• ALL -所有消息
• UNSEEN -未读邮件
• SEEN -阅读消息
• FLAGGED -标记的邮件
• FROM -来自特定发件人
• TO -致特定收件人
• SUBJECT -主题包含文本
• SINCE -日期之后（例如，“2024年3月14日”）
• BEFORE -日期之前

get_email

获取详细的电子邮件信息。

{
  "name": "get_email",
  "arguments": {
    "folder": "INBOX",
    "message_id": "1",
    "uid": "100",
    "include_body": true
  }
}

注： 提供其中之一 message_id 或 uid.

标记操作

mark_read

将电子邮件标记为已读（见）。

{
  "name": "mark_read",
  "arguments": {
    "folder": "INBOX",
    "message_id": "1"
  }
}

mark_unread

将电子邮件标记为未读。

{
  "name": "mark_unread",
  "arguments": {
    "folder": "INBOX",
    "uid": "100"
  }
}

mark_flagged

将电子邮件标记为标记（带星号）。

{
  "name": "mark_flagged",
  "arguments": {
    "folder": "INBOX",
    "message_id": "1"
  }
}

unmark_flagged

删除标记的状态。

{
  "name": "unmark_flagged",
  "arguments": {
    "folder": "INBOX",
    "message_id": "1"
  }
}

移动/复制操作

move_email

将电子邮件移动到另一个文件夹。

{
  "name": "move_email",
  "arguments": {
    "source_folder": "INBOX",
    "target_folder": "Archive",
    "message_id": "1"
  }
}

copy_email

将电子邮件复制到另一个文件夹。

{
  "name": "copy_email",
  "arguments": {
    "source_folder": "INBOX",
    "target_folder": "Archive",
    "uid": "100"
  }
}

删除

delete_email

删除电子邮件（标记为已删除并删除）。

{
  "name": "delete_email",
  "arguments": {
    "folder": "INBOX",
    "message_id": "1"
  }
}

SMTP发送

send_email

发送一封带有可选HTML正文和附件的电子邮件。

{
  "name": "send_email",
  "arguments": {
    "to": ["recipient@example.com"],
    "subject": "Email Subject",
    "body_text": "Plain text body",
    "body_html": "
HTML body
",
    "cc": ["cc@example.com"],
    "bcc": ["bcc@example.com"],
    "attachments": [
      {
        "filename": "document.pdf",
        "content_type": "application/pdf",
        "data_base64": "JVBERi0xLjQK..."
      }
    ]
  }
}

发送附件：

将文件内容编码为base64：

import base64

with open("report.zip", "rb") as f:
    data_base64 = base64.b64encode(f.read()).decode()

# Then use in MCP call

常见内容类型：

send_reply

回复电子邮件。

{
  "name": "send_reply",
  "arguments": {
    "to": ["recipient@example.com"],
    "subject": "Re: Original Subject",
    "body_text": "Reply text",
    "reply_to_message_id": "",
    "quote_original": true
  }
}

send_forward

将电子邮件转发给其他收件人。

{
  "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:"
  }
}

公用事业

get_current_date

获取当前日期和时间。

{
  "name": "get_current_date",
  "arguments": {}
}

技能

项目包含一个 OpenClaw skill，帮助用户更好地使用邮件服务。

安装 Skill

# 复制到 OpenClaw skills 目录
cp -r skills/mail-skill ~/.openclaw/skills/

Skill 功能

• 自动检查 mail-mcp 是否已安装
• 提供常见邮箱配置示例
• mcporter 使用示例

详见 技能/邮件技能/skill.md

测试

# 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

测试状态：

• SMTP测试：通过21次✅
• IMAP集成：通过17次✅
• 单元测试：64项通过（遗留测试中的一些模拟问题）

项目结构

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": "Error message description"
}

SMTP错误包括特定的异常类型：

• SMTPConnectionError -连接失败
• SMTPAuthError -身份验证失败
• SMTPSendError -发送失败
• SMTPRecipientsError -收件人无效

支持的电子邮件提供商

许可证

麻省理工学院