email-mcp

用于单个邮箱的轻量级个人 MCP 服务器，基于 IMAP + SMTP。

主要面向个人使用场景：

• 单个邮箱

• 通过环境变量提供凭据

• 通过 IMAP 读取邮件

• 通过 SMTP 发送邮件

• 可与 Yandex Mail 默认设置良好配合，也可指向任何 IMAP/SMTP 提供商

我做了哪些更改

此仓库最初仅在 stdio 模式下工作。这对于本地 MCP 客户端来说没问题，但 ChatGPT Web 集成需要 HTTP MCP 端点。服务器现在支持：

• 用于本地/开发使用的 stdio

• 用于 ChatGPT Web 应用的 streamable-http

• 用于兼容性的 sse

我还修复了一个邮件线程问题：

• 旧的 reply_to 参数仅设置了 Reply-To 标头

• 真正的回复通常应使用 In-Reply-To 和 References

• read_email 现在会返回这些标头，以便可以将它们传回 send_email

并且我改进了 read_email 的输出，现在会返回：

• 解码后的标头

• 附件元数据

• 消息线程标头

Related MCP server: IMAP/SMTP Email MCP Server

附件支持

此版本支持读取和发送附件。

从收到的邮件中下载附件

1. 调用 read_email(uid=..., folder="INBOX")

2. 检查 attachments 列表

3. 使用 attachment_index 调用 get_attachment(...)

get_attachment(...) 返回：

• filename

• content_type

• size_bytes

• content_base64

在发出的邮件中发送附件

send_email(...) 接受一个 attachments 列表。

每个项目可以是以下之一：

{"path": "/path/to/file.pdf"}

{"filename": "note.txt", "content_text": "hello from MCP"}

{"filename": "report.pdf", "content_base64": "JVBERi0x...", "content_type": "application/pdf"}

已发送文件夹行为

SMTP 发送成功后，相同的 MIME 消息会被追加到您的 IMAP 已发送文件夹中。

默认情况下，该文件夹名称为：

Sent

如果您的邮箱使用不同的 IMAP 文件夹名称，您可以覆盖它：

export SENT_FOLDER="Sent"
# or
export MAILBOX_SENT_FOLDER="Sent"

如果已发送邮件未显示，请先运行 list_folders() 并使用您的邮箱返回的确切文件夹名称。

文件

• server.py — MCP 工具定义和传输启动

• mail_ops.py — IMAP/SMTP 实现

• requirements.txt — Python 依赖项

环境

必需：

export MAILBOX_EMAIL="you@example.com"
export MAILBOX_PASSWORD="your-app-password"

可选的提供商设置：

export IMAP_HOST="imap.yandex.com"
export IMAP_PORT="993"
export SMTP_HOST="smtp.yandex.com"
export SMTP_PORT="465"

可选的已发送文件夹设置：

export SENT_FOLDER="Sent"

可选的 MCP 服务器设置：

export MCP_TRANSPORT="stdio"
export MCP_HOST="0.0.0.0"
export MCP_PORT="8000"

为方便起见，也支持别名：

export YANDEX_EMAIL="you@yandex.ru"
export YANDEX_APP_PASSWORD="..."

安装

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

本地运行 (stdio)

python server.py

这是直接启动进程的本地 MCP 客户端的正确模式。

为 ChatGPT Web 应用运行

ChatGPT Web 需要一个公共 HTTPS MCP 端点。以 HTTP 模式启动服务器：

python server.py --transport streamable-http --host 0.0.0.0 --port 8000

然后通过公共 HTTPS 隧道或反向代理暴露该端口，并在 ChatGPT 中注册生成的 MCP URL。

暴露的工具

list_folders()

列出可用的 IMAP 文件夹。

search_emails(folder="INBOX", text=None, unseen_only=False, since_date=None, limit=30)

按 IMAP 条件搜索消息。

返回如下项目：

• uid

• subject

• from

• to

• date

• flags

• size_bytes

read_email(uid, folder="INBOX")

获取完整消息而不将其标记为已读。

返回：

• 解码后的标头

• message_id

• in_reply_to

• references

• attachments

• body_plain

• body_html

get_attachment(uid, folder="INBOX", attachment_index=None, filename=None)

获取单个附件并将其作为 base64 返回。

send_email(...)

通过 SMTP 发送消息。

重要参数：

• reply_to_header — 设置 Reply-To 标头

• in_reply_to — 线程标头

• references — 线程标头

• attachments — 可选的附件规范列表

对于真正的回复，请使用 in_reply_to，通常也使用 references。

Yandex 注意事项

典型的 Yandex 默认设置是：

• IMAP: imap.yandex.com:993 (通过 SSL/TLS)

• SMTP: smtp.yandex.com:465 (通过 SSL/TLS)

请使用 应用密码，而不是您的主账户密码。

下一步合理的升级

• 内联/嵌入式图像附件

• 附件大小限制和流式传输

• 带有确认的移动/归档/删除工具

• OAuth 而非基于环境变量的凭据

• 使用模拟 IMAP/SMTP 后端的测试