IMAP MCP 服务器

模型上下文协议 (MCP) 服务器，使 AI 助手能够检查电子邮件、处理消息并通过交互了解用户偏好。

概述

该项目实现了一个与 IMAP 电子邮件服务器交互的 MCP 服务器，以提供以下功能：

电子邮件浏览和搜索
电子邮件组织（移动、标记、标记）
电子邮件撰写和回复
交互式电子邮件处理和学习用户偏好
自动电子邮件摘要和分类
支持多个 IMAP 提供商

IMAP MCP 服务器旨在与 Claude 或任何其他兼容 MCP 的助手协同工作，使它们能够充当智能电子邮件助手，随着时间的推移了解您的偏好。

特征

电子邮件身份验证：使用各种身份验证方法安全访问 IMAP 服务器
电子邮件浏览：列出带有过滤选项的文件夹和消息
电子邮件内容：阅读邮件内容，包括文本、HTML 和附件
电子邮件操作：移动、删除、标记为已读/未读、标记邮件
电子邮件撰写：草拟并以适当的格式保存对邮件的回复
- 支持纯文本和 HTML 回复
- 支持 CC 的“回复全部”功能
- 使用“回复”和“参考”标题进行正确的线索
- 将草稿保存到适当的文件夹
搜索：跨文件夹的基本搜索功能
交互模式：处理电子邮件和学习偏好的结构化模式（计划中）
学习层：记录并分析用户决策以预测未来的行动（计划）

当前项目结构

该项目目前组织如下：

.
├── examples/              # Example configurations
│   └── config.yaml.example
├── imap_mcp/              # Source code
│   ├── __init__.py
│   ├── config.py          # Configuration handling
│   ├── imap_client.py     # IMAP client implementation
│   ├── models.py          # Data models
│   ├── resources.py       # MCP resources implementation
│   ├── server.py          # Main server implementation
│   └── tools.py           # MCP tools implementation
├── tests/                 # Test suite
│   ├── __init__.py
│   └── test_models.py
├── INSTALLATION.md        # Detailed installation guide
├── pyproject.toml         # Project configuration
└── README.md              # This file

入门

先决条件

Python 3.8 或更高版本
启用 IMAP 的电子邮件帐户（推荐使用 Gmail）
uv用于包管理和运行 Python 脚本

安装

如果尚未安装 uv，请安装：
curl -LsSf https://astral.sh/uv/install.sh | sh
克隆并安装包：
git clone https://github.com/non-dirty/imap-mcp.git cd imap-mcp uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate uv pip install -e ".[dev]"

Gmail 配置

创建配置文件：
cp config.sample.yaml config.yaml
设置 Gmail OAuth2 凭据：
- 前往Google Cloud Console
- 创建新项目或选择现有项目
- 启用 Gmail API
- 创建 OAuth2 凭据（桌面应用程序类型）
- 下载客户端配置
使用您的 Gmail 设置更新config.yaml ：
imap: host: imap.gmail.com port: 993 username: your-email@gmail.com use_ssl: true oauth2: client_id: YOUR_CLIENT_ID client_secret: YOUR_CLIENT_SECRET refresh_token: YOUR_REFRESH_TOKEN

用法

查看电子邮件

要列出收件箱中的电子邮件：

uv run list_inbox.py --config config.yaml --folder INBOX --limit 10

可用选项：

--folder ：指定要检查的文件夹（默认值：INBOX）
--limit ：显示的电子邮件的最大数量（默认值：10）
--verbose ：启用详细日志输出

启动 MCP 服务器

要启动 IMAP MCP 服务器：

uv run imap_mcp.server --config config.yaml

对于带调试的开发模式：

uv run imap_mcp.server --dev

管理 OAuth2 令牌

要刷新您的 OAuth2 令牌：

uv run imap_mcp.auth_setup refresh-token --config config.yaml

要生成新的 OAuth2 令牌：

uv run imap_mcp.auth_setup generate-token --config config.yaml

发展

设置开发环境

# Set up virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -e ".[dev]"

运行测试

pytest

安全注意事项

此 MCP 服务器需要访问您的电子邮件帐户，其中包含敏感的个人信息。请注意以下安全注意事项：

使用环境变量或安全凭证存储安全地存储电子邮件凭证
考虑使用应用专用密码，而不是主账户密码
将文件夹访问权限限制为仅对您的用例必要的内容
查看电子邮件提供商设置中授予服务器的权限

项目路线图

[x] 项目初始化和存储库设置
[x] 基本 IMAP 集成
[x] 电子邮件资源实现
[x] 电子邮件工具实现
[x] 电子邮件回复和草稿功能
[ ] 用户偏好学习实现
[ ] 高级搜索功能
[ ] 多账户支持
[ ] 与主要电子邮件提供商集成

贡献

欢迎贡献！请参阅CONTRIBUTING.md获取相关指南。

执照

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。

致谢

用于提供框架的模型上下文协议
人类学为克劳德的发展
使该项目成为可能的各种 Python IMAP 库

IMAP MCP Server

Integrations