gmail-mcp-server-btq

🚀 Gmail MCP 服务器

该项目实现了一个模型上下文协议 (MCP) 服务器，可借助 IMAP 和 SMTP 与 Gmail 账户进行交互。它提供了一系列实用工具，能用于搜索邮件、检索邮件内容、管理标签（创建、删除、重命名、应用、移除）以及发送/转发邮件。

✨ 主要特性

• 邮件搜索：可依据日期范围、关键字或原始 Gmail 查询字符串来搜索邮件。支持在特定文件夹（如收件箱、已发送）中搜索，并能限制搜索结果数量。借助 Gmail 的 X - GM - RAW 扩展，能实现高效的收件箱搜索（例如按 category:primary 过滤）。
• 邮件内容检索：通过序列 ID 可获取特定邮件的完整内容，包括头信息、正文和附件。
• 标签管理 (CRUD)：
  • 列出所有可用的 Gmail 标签（文件夹）。
  • 创建新的自定义标签。
  • 重命名现有的标签。
  • 删除现有的自定义标签（系统标签无法删除）。
  • 将标签应用到单个邮件上。
  • 移除单个邮件上的标签。
• 批处理操作：
  • 利用序列 ID 批量为多个邮件应用标签。
  • 从多个邮件上批量移除标签。
  • 将多个邮件移动到特定标签/文件夹中。
• 发送邮件：可发送新邮件（需要进行 SMTP 配置）。
• 转发邮件：能转发现有邮件，包括附件（需要进行 SMTP 配置）。
• 每日邮件计数：可统计指定日期范围内每天收到的邮件数量。

📚 详细文档

项目结构

.
├── .gitignore         # 指定 Git 应忽略的文件
├── .python-version    # 指定 Python 版本（用于 pyenv）
├── LICENSE            # 项目许可证文件
├── pyproject.toml     # Python 项目配置（依赖项、构建系统）
├── README.md          # 此文件
├── task_list.md       # 跟踪开发进度
├── uv.lock            # uv 包管理器的锁定文件
├── src/
│   └── email_client/
│       ├── __init__.py
│       ├── config.py        # 处理从环境变量（.env）加载配置
│       ├── handlers.py      # 实现处理 MCP 工具调用逻辑
│       ├── imap_client.py   # 包含与 IMAP 服务器交互的函数
│       ├── server.py        # 使用 @modelcontextprotocol/sdk 的主 MCP 服务器脚本
│       ├── smtp_client.py   # 包含与 SMTP 服务器交互的函数
│       └── tool_definitions.py # 定义所有可用工具及其详细输入模式

可用工具（摘要）

• search - emails：搜索邮件。
• get - email - content：获取完整的邮件详情。
• count - daily - emails：统计每天收到的邮件数量。
• list - labels：列出所有标签/文件夹。
• create - label：创建新的标签。
• rename - label：重命名现有标签。
• delete - label：删除标签。
• apply - label：将标签应用到单个邮件上。
• remove - label：移除单个邮件上的标签。
• apply - label - batch：批量为多个邮件应用标签。
• remove - label - batch：从多个邮件上批量移除标签。
• move - email：将单个邮件移动到一个标签中。
• move - email - batch：将多个邮件移动到一个标签中。
• send - email：发送新邮件。
• forward - email：转发现有邮件。

有关每个工具的详细输入模式，请参阅 src/email_client/tool_definitions.py。

🚀 快速开始

1. 克隆仓库：

git clone https://github.com/yourusername/gmail-mcp-server.git
cd gmail-mcp-server

2. 创建虚拟环境并安装依赖项：

python -m venv .venv
source .venv/bin/activate  # 在 Windows 上使用 .venv\Scripts\activate
pip install -r requirements.txt

3. 配置环境变量： 创建一个 .env 文件，添加以下内容：

Gmail_IMAP_HOST=imap.gmail.com
Gmail_SMTP_HOST=smtp.gmail.com
Gmail_PORT=143  # IMAP 端口
Gmail_SSL_PORT=465  # SMTP SSL 端口
Gmail_EMAIL=your_email@gmail.com
Gmail_PASSWORD=your_app_specific_password

4. 运行服务器：

source .venv/bin/activate  # 在 Windows 上使用 .venv\Scripts\activate
python src/email_client/server.py