IMAP邮件管理器

@non-dirty/imap-mcp

3 Stars 615 次浏览 non-dirty 更新于 2026-08-23

一种模型上下文协议服务器，使AI助手能够通过IMAP访问和管理电子邮件，支持浏览、搜索、阅读和整理邮件，并随着时间的推移学习用户的偏好。

交流协作工具

该服务暂未提供标准配置，请参考 README 手动接入

服务介绍

IMAP MCP 服务器

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

概述

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

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

IMAP MCP服务器被设计成可以与Claude或任何其他兼容MCP的助手一起工作，使它们能够作为智能邮件助手，随着时间的推移学习您的偏好。

功能

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

当前项目结构

项目目前按如下方式组织：

.
├── 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  # 在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 服务器需要访问您的电子邮件帐户，其中包含敏感的个人信息。请注意以下安全注意事项：

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

项目路线图

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

贡献

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

许可证

该项目根据 MIT 许可证许可 - 详情请参见 LICENSE 文件。

致谢

Model Context Protocol 提供了框架
Anthropic 开发了 Claude
各种使该项目成为可能的 Python IMAP 库

查看源码项目主页