IMAP MCP 服务器

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

概述

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

• 电子邮件浏览和搜索

• 电子邮件组织（移动、标记、标记）

• 电子邮件撰写和回复

• 交互式电子邮件处理和学习用户偏好

• 自动电子邮件摘要和分类

• 支持多个 IMAP 提供商

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

Related MCP server: Enhanced Gmail MCP Server

特征

• 电子邮件身份验证：使用各种身份验证方法安全访问 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 脚本

安装

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  # On 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

发展

设置开发环境

# 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 库