IMAP MCP 服务器

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

概述

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

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

IMAP MCP 服务器旨在与 Claude 或任何其他 MCP 兼容的助手一起使用，允许它们充当智能电子邮件助手，随着时间的推移学习您的偏好。

特性

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

当前项目结构

该项目目前的组织结构如下：

.
├── examples/              # 示例配置
│   └── config.yaml.example
├── imap_mcp/              # 源代码
│   ├── __init__.py
│   ├── config.py          # 配置处理
│   ├── imap_client.py     # IMAP 客户端实现
│   ├── models.py          # 数据模型
│   ├── resources.py       # MCP 资源实现
│   ├── server.py          # 主服务器实现
│   └── tools.py           # MCP 工具实现
├── tests/                 # 测试套件
│   ├── __init__.py
│   └── test_models.py
├── INSTALLATION.md        # 详细安装指南
├── pyproject.toml         # 项目配置
└── README.md              # 本文件

入门

前提条件

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

安装

1. 如果您尚未安装 uv，请安装它：

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. 克隆并安装软件包：

   git clone https://github.com/non-dirty/imap-mcp.git
   cd imap-mcp
   uv venv
   source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate
   uv pip install -e ".[dev]"
   

Gmail 配置

1. 创建一个配置文件：

   cp config.sample.yaml config.yaml
   

2. 设置 Gmail OAuth2 凭据：

   • 转到 Google Cloud Console
   • 创建一个新项目或选择现有项目
   • 启用 Gmail API
   • 创建 OAuth2 凭据（桌面应用程序类型）
   • 下载客户端配置

3. 使用您的 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

开发

设置开发环境

# 设置虚拟环境
python -m venv venv
source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate

# 安装开发依赖项
pip install -e ".[dev]"

运行测试

pytest

安全注意事项

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

• 使用环境变量或安全凭据存储安全地存储电子邮件凭据
• 考虑使用应用专用密码而不是您的主帐户密码
• 限制文件夹访问权限，仅限于您的用例所需的内容
• 查看您在电子邮件提供商设置中授予服务器的权限

项目路线图

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

贡献

欢迎贡献！ 请参阅 CONTRIBUTING.md 了解指南。

许可证

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

致谢

• 模型上下文协议 提供框架
• Anthropic 开发 Claude
• 使该项目成为可能的各种 Python IMAP 库