AI导哈

邮件管理服务

通过标准化的MCP接口提供完整的IMAP电子邮件操作和SMTP发送功能。

  • by AdJIa
  • Python
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 AdJIa/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设置

变量 描述 默认值
IMAP_HOST IMAP服务器主机名 imap.example.com
IMAP_PORT IMAP服务器端口 993
EMAIL_USER 电子邮件用户名 -
EMAIL_PASSWORD 电子邮件密码 -
IMAP_SSL 使用SSL连接 true

SMTP设置

变量 描述 默认值
SMTP_HOST SMTP服务器主机名 smtp.example.com
SMTP_PORT SMTP服务器端口 465
EMAIL_USER 电子邮件用户名（与IMAP相同） -
EMAIL_PASSWORD 电子邮件密码（与IMAP相同） -
SMTP_SSL 使用SSL/TLS（端口465） true
SMTP_STARTTLS 使用STARTTLS（端口587） false

示例

# 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 <email> -来自特定发件人
  • TO <email> -致特定收件人
  • SUBJECT <text> -主题包含文本
  • SINCE <date> -日期之后（例如，“2024年3月14日”）
  • BEFORE <date> -日期之前

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": "<p>HTML body</p>",
    "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

常见内容类型：

文件类型 内容类型
PDF application/pdf
拉链 application/zip
Excel application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Word application/vnd.openxmlformats-officedocument.wordprocessingml.document
图像（PNG） image/png
图像（JPEG） image/jpeg
文本 text/plain

send_reply

回复电子邮件。

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

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

{
  "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 -收件人无效

支持的电子邮件提供商

提供商 IMAP主机 SMTP主机 备注
Gmail imap.gmail.com smtp.gmail.com 需要应用程序密码
展望 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 需要授权码

许可证

麻省理工学院

相关 MCP