MCP IMAP服务器
轻量级 模型上下文协议（MCP） 通过工具公开IMAP邮箱的服务器，使AI助手能够与您的电子邮件进行交互。
特性
- 🔍 搜索电子邮件 具有灵活的标准（发件人、主题、日期范围、文本等）
- 📬 列出邮箱 IMAP帐户中的文件夹
- 📧 检索邮件 包含完整的标题、正文内容和附件元数据
- 📎 下载附件 （base64编码）
- ✅ 标记消息 可见/不可见
- 🔒 安全 -使用标准IMAP身份验证
- 🌐 灵活部署 -支持本地（stdio）和远程（HTTP）模式
安装
先决条件
- Python 3.10或更高版本
- 支持IMAP的电子邮件帐户（Gmail、Outlook等）
设置
- 克隆此存储库：
git clone
cd mcp-imap-server- 创建并激活虚拟环境：
python3 -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate- 安装软件包：
pip install -U pip
pip install -e .配置
环境变量
复制 .env.example 到 .env 并配置您的IMAP设置：
cp .env.example .env必需设置
IMAP_HOST-您的IMAP服务器主机名（例如。，imap.gmail.com)IMAP_USERNAME-您的电子邮件地址或用户名IMAP_PASSWORD-您的密码或特定于应用程序的密码
可选设置
IMAP_PORT-IMAP服务器端口（默认值：993)IMAP_SSL-使用SSL/TLS连接（默认：true)IMAP_STARTTLS-使用STARTTLS（默认值：false)IMAP_TIMEOUT_SECONDS-连接超时（默认值：30)
电子邮件提供商示例
Gmail：
IMAP_HOST=imap.gmail.com
IMAP_USERNAME=your-email@gmail.com
IMAP_PASSWORD=your-app-password*注意：Gmail需要 应用程序特定密码 当2FA启用时。*
Outlook/Office 365：
IMAP_HOST=outlook.office365.com
IMAP_USERNAME=your-email@outlook.com
IMAP_PASSWORD=your-password用法
使用Docker运行（推荐）
运行服务器最简单的方法是使用Docker：
- 构建Docker镜像：
docker build -t mcp-imap-server .- 使用环境变量运行：
docker run -d \
--name mcp-imap-server \
-p 8993:8993 \
-e IMAP_HOST=imap.gmail.com \
-e IMAP_USERNAME=your-email@gmail.com \
-e IMAP_PASSWORD=your-app-password \
mcp-imap-server- 或者使用docker compose
.env文件：
docker-compose up -d服务器将在以下时间可用 http://localhost:8993/mcp
要查看日志，请执行以下操作：
docker logs -f mcp-imap-server停止：
docker-compose down
# or
docker stop mcp-imap-server以HTTP服务器（本机）运行
此模式允许其他机器（如Warp）上的AI客户端连接到您的电子邮件服务器：
source .venv/bin/activate
# Listen on all interfaces
MCP_HOST=0.0.0.0 MCP_PORT=8993 mcp-imap-server
# Or listen on localhost only (more secure)
MCP_HOST=127.0.0.1 MCP_PORT=8993 mcp-imap-serverMCP端点将在以下位置可用：
- 当地：
http://127.0.0.1:8993/mcp - 远程：
http://:8993/mcp
您可以通过以下方式测试服务器：
curl http://localhost:8993/health在stdio模式下运行（本地进程）
对于将服务器作为子进程生成的本地AI客户端：
source .venv/bin/activate
MCP_TRANSPORT=stdio mcp-imap-server与Warp连接
在Warp中，通过添加到MCP设置来配置MCP服务器：
{
"mcpServers": {
"imap": {
"url": "http://:8993/mcp"
}
}
}可用工具
服务器公开了以下MCP工具：
list_mailboxes
返回IMAP帐户中的所有可用邮箱/文件夹。
退货： 包含名称、分隔符和标志的邮箱列表。
search_messages
搜索具有各种条件的邮件。
参数：
mailbox（str，默认值：“INBOX”）-要搜索的邮箱from_（str，可选）-按发件人电子邮件筛选to（str，可选）-按收件人电子邮件筛选subject（str，可选）-按主题文本筛选text（str，可选）-在邮件正文中搜索unseen（bool，可选）-按已读/未读状态筛选since（str，可选）-自日期（YYYY-MM-DD）以来的消息before（str，可选）-日期（YYYY-MM-DD）之前的消息limit（int，默认值：20）-最大结果数
退货： 包含UID、主题、发件人、日期、标志和大小的邮件摘要列表。
get_message
按UID检索完整消息内容。
参数：
uid（int，必填）-消息UIDmailbox（str，默认值：“INBOX”）-包含邮件的邮箱include_body（bool，默认值：true）-包含消息正文include_html（bool，默认值：false）-包含HTML正文max_body_chars（int，默认值：20000）-最大正文长度
退货： 包含标题、正文、标志和附件元数据的完整邮件。
download_attachment
按UID下载邮件附件。
参数：
uid（int，必填）-消息UIDmailbox（str，默认值：“INBOX”）-包含邮件的邮箱attachment_index（int，默认值：0）-附件之间基于0的索引filename（str，可选）-文件名完全匹配（已知时首选）offset_bytes（int，默认值：0）-开始偏移到附件负载中（用于分块下载）max_bytes（int，默认值：10000000）-如果>0，则将返回的字节截断到此限制
退货： 附件元数据+ content_base64.
set_seen
将邮件标记为已读或未读。
参数：
uid（int，必填）-消息UIDmailbox（str，默认值：“INBOX”）-包含邮件的邮箱seen（bool，默认值：true）-标记为可见（true）或不可见（false）
退货： 更新了消息标志。
安全注意事项
- ⚠️ 应用程序特定密码：尽可能使用特定于应用程序的密码，而不是您的主帐户密码
- 🔒 防火墙：如果在HTTP模式下运行
0.0.0.0，确保防火墙适当限制访问 - 🌐 网络：对于远程访问，考虑使用VPN或SSH隧道，而不是将服务器直接暴露在互联网上
- 📝 环境变量：永远不要承诺你的
.env文件-它已经在.gitignore - 🔑 默认情况下为只读：大多数操作都是只读的，除了
set_seen
发展
项目结构
mcp-imap-server/
├── src/
│ └── mcp_imap_server/
│ ├── __init__.py
│ ├── __main__.py
│ ├── server.py # Main MCP server and tool definitions
│ ├── config.py # Configuration management
│ └── imap.py # IMAP client wrapper
├── pyproject.toml
├── README.md
├── .env.example
└── .gitignore运行测试
要测试服务器功能，请执行以下操作：
- 确保您的
.env文件配置正确 - 在一个终端中启动服务器
- 使用MCP客户端或curl测试端点
故障排除
连接错误
- 验证您的IMAP凭据是否正确
- 检查您的电子邮件提供商是否需要特定于应用程序的密码
- 确保IMAP端口（通常为993）未被防火墙阻止
- 尝试通过检查服务器输出启用调试日志记录
身份验证失败
- 一些提供商（如Gmail）要求启用“不太安全的应用程序访问”或使用OAuth2
- 启用2FA时使用特定于应用程序的密码
- 验证用户名格式（一些提供商需要完整的电子邮件，其他提供商只需要用户名）
演出
- 使用
limit参数在search_messages减小结果大小 - 调整
max_body_chars在get_message限制正文内容大小 - 考虑使用
unseen筛选器仅获取未读邮件
许可证
仅限GPL-3.0–有关详细信息，请参阅许可证文件。
贡献
欢迎投稿！请随时提交拉取请求。
支持
如果您遇到问题或有疑问，请在GitHub存储库上打开问题。