email-mcp

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

它主要针对私人设置：

• 单个邮箱

• 通过环境变量提供凭据

• 通过 IMAP 读取邮件

• 通过 SMTP 发送邮件

• 可与 Yandex Mail 默认设置良好配合，但也适用于任何 IMAP/SMTP 提供商

我做了哪些更改

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

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

• 用于 ChatGPT Web 应用的 streamable-http

• 用于兼容性的 sse

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

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

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

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

我还改进了 read_email 的输出，增加了以下返回内容：

• 解码后的标头

• 附件元数据

• 消息线程标头

文件

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

可选 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

send_email(...)

通过 SMTP 发送消息。

重要参数：

• reply_to_header — 设置 Reply-To 标头

• in_reply_to — 线程标头

• references — 线程标头

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

Yandex 注意事项

典型的 Yandex 默认设置是：

• IMAP: imap.yandex.com:993 (基于 SSL/TLS)

• SMTP: smtp.yandex.com:465 (基于 SSL/TLS)

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

下一步合理的升级

• 附件下载工具

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

• 使用 OAuth 代替基于环境变量的凭据

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