🚀 Gmail MCP 服务器

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

🚀 快速开始

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
   

✨ 主要特性

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

📚 详细文档

可用工具（摘要）

• 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。

🔧 技术细节

项目结构

.
├── .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 # 定义所有可用工具及其详细输入模式

📄 许可证

项目许可证文件为 LICENSE，具体许可信息可查看该文件。