MCP Email Server

MCP Email Server

用于电子邮件操作（通过 TLS 使用 POP3/SMTP）的 Model Context Protocol（MCP）服务。允许 Claude 等大模型读取、发送和管理电子邮件。

快速开始

选项 1：uvx（推荐）

无需克隆，无需安装——直接从 GitHub 运行：

uvx git+https://github.com/ptbsare/email-mcp-server \
  --email-user [email protected] \
  --email-pass yourpassword \
  --pop3-server pop.example.com \
  --smtp-server smtp.example.com

首次运行时会缓存软件包；之后启动即刻完成。

选项 2：克隆并在本地运行

git clone https://github.com/ptbsare/email-mcp-server
cd email-mcp-server
uv pip install -e .
uv run main.py --email-user [email protected] --email-pass yourpassword \
  --pop3-server pop.example.com --smtp-server smtp.example.com

选项 3：.env 文件

在工作目录中创建 .env 文件：

[email protected]
EMAIL_PASS=yourpassword
POP3_SERVER=pop.example.com
SMTP_SERVER=smtp.example.com

然后只需运行：

uvx git+https://github.com/ptbsare/email-mcp-server
# or
uv run main.py

配置

配置优先级（从高到低）

1. CLI 参数——覆盖所有其他配置
2. 环境变量——覆盖 .env 文件
3. .env 文件——备用默认值

所有配置选项

CLI 参数	环境变量	必需	默认值	说明
--email-user	EMAIL_USER	✅	—	电子邮件地址
--email-pass	EMAIL_PASS	✅	—	电子邮件密码／应用专用密码
--pop3-server	POP3_SERVER	✅	—	POP3 服务主机名
--pop3-port	POP3_PORT		995	POP3 SSL 端口
--smtp-server	SMTP_SERVER	✅	—	SMTP 服务主机名
--smtp-port	SMTP_PORT		587	SMTP 端口（使用 --smtp-use-ssl 时自动设为 465）
--smtp-use-ssl	SMTP_USE_SSL		false	使用 SMTP_SSL（端口 465），而非 STARTTLS
--log-level	LOG_LEVEL		INFO	日志级别：DEBUG / INFO / WARNING / ERROR

示例：混合使用配置来源

# CLI args only (no .env needed):
uv run main.py --email-user [email protected] --email-pass xxx \
  --pop3-server pop.gmail.com --smtp-server smtp.gmail.com

# .env file for credentials, CLI for servers:
# .env: [email protected] / EMAIL_PASS=xxx
uv run main.py --pop3-server pop.gmail.com --smtp-server smtp.gmail.com

# Env vars override .env:
[email protected] uv run main.py --pop3-server pop.gmail.com ...

与 Claude Desktop 配合使用

将以下内容添加到 Claude Desktop 配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%/Claude/claude_desktop_config.json

在配置文件中使用环境变量：

{
  "mcpServers": {
    "email-mcp-server": {
      "command": "uvx",
      "args": ["git+https://github.com/ptbsare/email-mcp-server"],
      "env": {
        "EMAIL_USER": "[email protected]",
        "EMAIL_PASS": "your-app-password",
        "POP3_SERVER": "pop.example.com",
        "SMTP_SERVER": "smtp.example.com"
      }
    }
  }
}

在配置文件中使用 CLI 参数：

{
  "mcpServers": {
    "email-mcp-server": {
      "command": "uvx",
      "args": [
        "git+https://github.com/ptbsare/email-mcp-server",
        "--email-user", "[email protected]",
        "--email-pass", "your-app-password",
        "--pop3-server", "pop.example.com",
        "--smtp-server", "smtp.example.com"
      ]
    }
  }
}

提示： 可以同时使用 env 部分和 CLI 参数。CLI 参数始终具有最高优先级。

功能

• 轮询电子邮件： 列出收件箱电子邮件的标头，并可配置数量上限（pollEmails）
• 获取完整电子邮件： 按 ID 获取完整电子邮件内容，并自动提取附件（getEmailsById）
• 删除电子邮件： 按 ID 删除电子邮件（deleteEmailsById）
• 发送电子邮件： 发送纯文本（sendTextEmail）或 HTML（sendHtmlEmail）邮件，并可选择添加文件附件
• 安全连接： 通过 SSL 使用 POP3（端口 995），通过 STARTTLS（端口 587）或直接 SSL（端口 465）使用 SMTP
• 附件支持： 将本地文件作为附件发送；收到的附件会自动保存到 /tmp/email_mcp_attachments/<email_id>/

工具

pollEmails(limit=50)

列出最近的电子邮件标头（不含正文）。按时间从新到旧排列。先使用此工具获取 getEmailsById／deleteEmailsById 所需的 ID。

参数	类型	默认值	说明
limit	int	50	返回的电子邮件数量上限，按时间从新到旧排列

返回： [{"id": int, "Subject": str, "From": str, "Date": str, "Message-ID": str}]

pollEmails(limit=10)   # 10 most recent
pollEmails()           # default 50

---

getEmailsById(ids)

按 pollEmails 返回的 ID 获取完整电子邮件内容（标头和正文）。附件会自动保存到 /tmp/email_mcp_attachments/<id>/。

参数	类型	必需	说明
ids	list[int]	✅	来自 pollEmails() 的电子邮件 ID。示例：[1, 3, 5]

返回： [{"id": int, "headers": dict, "body": str, "attachments": [{"filename": str, "local_path": str, "size": int, "content_type": str}]}]

getEmailsById(ids=[1, 3, 5])

---

deleteEmailsById(ids)

按 ID 永久删除电子邮件。**无法撤销。**请先调用 pollEmails。

参数	类型	必需	说明
ids	list[int]	✅	来自 pollEmails() 的电子邮件 ID。示例：[1, 2, 3]

返回： {"deleted": [int], "failed": {"id": "error msg"}}

deleteEmailsById(ids=[1, 2, 3])

---

sendTextEmail(toAddresses, subject, body, attachments=None)

发送纯文本邮件。附件：本地文件路径列表，例如 ["/tmp/file.pdf"]。

Parameter	Type	Required	Default	Description
toAddresses	list[str]	✅	—	收件人。例如：["[email protected]"]
subject	str	✅	—	邮件主题
body	str	✅	—	纯文本正文
attachments	list[str]		None	本地文件路径。例如：["/tmp/report.pdf"]

返回： {"status": "success"}

sendTextEmail(
    toAddresses=["[email protected]"],
    subject="Hello",
    body="Hi Alice!",
    attachments=["/tmp/report.pdf"]
)

---

sendHtmlEmail(toAddresses, subject, body, attachments=None)

发送 HTML 邮件。附件：本地文件路径列表，例如 ["/tmp/file.png"]。

Parameter	Type	Required	Default	Description
toAddresses	list[str]	✅	—	收件人。例如：["[email protected]"]
subject	str	✅	—	邮件主题
body	str	✅	—	HTML 内容。例如："<h1>Hi</h1><p>Hello!</p>"
attachments	list[str]		None	本地文件路径。例如：["/tmp/chart.png"]

返回： {"status": "success"}

sendHtmlEmail(
    toAddresses=["[email protected]"],
    subject="Report",
    body="<h1>Report</h1><p>Sales up <b>20%</b>.</p>",
    attachments=["/tmp/chart.png"]
)

---

开发设置

前置条件

• Python 3.12+
• uv

步骤

git clone https://github.com/ptbsare/email-mcp-server
cd email-mcp-server
uv pip install -e .
uv run main.py --help

重要说明

• 应用专用密码： 如果你的邮件服务提供商使用双重身份验证（2FA），请为 EMAIL_PASS 生成应用专用密码
• 邮件 ID： POP3 ID 仅在会话期间有效。调用 getEmailsById() 或 deleteEmailsById() 前，请先调用 pollEmails()
• 附件存储： 收到的附件会保存到 /tmp/email_mcp_attachments/<email_id>/
• 安全性： 切勿提交 .env 文件——它已列入 .gitignore
• 配置优先级： CLI 参数 > 环境变量 > .env 文件

项目结构

email-mcp-server/
├── main.py              # MCP server entry point (all logic)
├── pyproject.toml       # Package config & dependencies
├── uv.lock              # Dependency lock file
├── .env                 # Credentials (create your own)
├── .gitignore
└── README.md

许可证

MIT