星战科技xingzhan.cloud
返回市场
imap-mcp

imap-mcp

作者：non-dirty30 星标更新：2025-04-03
安装使用来源：spider==github.com

项目介绍

IMAP MCP 服务器

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

概述

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

  • 邮件浏览和搜索
  • 邮件组织（移动、标记、标记已读/未读）
  • 邮件撰写和回复
  • 交互式邮件处理和学习用户偏好
  • 自动邮件摘要和分类
  • 支持多个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. 更新config.yaml中的Gmail设置：

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

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

项目路线图

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

贡献

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

许可证

本项目根据MIT许可证发布 - 详情见LICENSE文件。

致谢