Name: 邮件自动化代理
Author: rmisegal

使用说明

Gmail MCP 代理：一个用于电子邮件自动化的智能子代理

作者约拉姆·塞加尔博士

许可证： 麻省理工学院（MIT）

概述

Gmail MCP代理是一个复杂且自包含的子代理，旨在弥合大型语言模型与个人电子邮件数据之间的鸿沟。它作为一个模型-上下文-策略（MCP）服务器，为用户的Gmail账户提供了一个安全的编程接口。通过利用谷歌Gemini AI的认知能力，该代理能够理解自然语言指令，根据复杂标准搜索电子邮件，并将结果导出为结构化的CSV格式，同时完全支持希伯来语和其他Unicode字符。

这个项目为构建能够在如Claude Code等更大系统中协同工作的专用AI代理提供了实践和学术参考。它展示了一种强大的架构，用于处理身份验证、数据处理以及确保安全性，同时提供了一个强大的工具，用于电子邮件自动化和数据提取。

目录

建筑

主要特点

入门指南

先决条件

安装

配置和认证

1. Gmail API 凭据

2. Gemini API密钥

3. 环境设置

4. 首次认证（OAuth 2.0）

使用方法

运行服务器

与Claude CLI的集成

运行测试

安全考虑因素

许可证

建筑学

该代理构建为一个基于Python的服务器，遵循模型-上下文-策略（MCP）协议。这使得它能够作为“工具”无缝集成到更高级的人工智能助手系统中。

核心组件包括：

MCP服务器（使用Flask和MCP库）： 一个轻量级的网络服务器，用于展示代理的功能（例如。， search_and_export_emails) 通过标准化协议进行。

Gmail API 客户端： 使用OAuth 2.0安全地与Gmail API交互，代表用户执行操作。它负责处理令牌的生成、刷新和存储。

双子座AI模型： 虽然当前的实现主要将其用于未来扩展的可能性，但它被用作解析自然语言的认知引擎。查询构建的核心逻辑是显式处理的。

认证管理器： 管理Gmail的OAuth 2.0流程以及Gemini API密钥的安全处理。

CSV 导出器： 将提取的电子邮件数据格式化为CSV文件，确保使用正确的编码（带BOM的UTF-8），以便与Microsoft Excel等电子表格软件兼容，特别是对于希伯来语等语言。

主要特点

安全认证： 使用官方的Google OAuth 2.0流程，以确保用户明确且可撤销地授权访问其Gmail帐户。

自然语言查询（通过Claude CLI）： 允许用户使用日常英语提出请求，例如“查找过去30天内带有‘发票’标签的电子邮件”

高级搜索： 支持按Gmail标签、开始日期和结束日期进行筛选。

结构化数据导出： 自动将搜索结果导出为格式整齐、清晰易读的CSV文件。

全面支持Unicode和希伯来语： 正确处理和编码电子邮件内容及CSV输出中的非ASCII字符，避免文本乱码。

全面测试： 包括一整套 pytest 进行测试以确保可靠性和正确性。

独立运行且可集成： 可以作为独立服务器运行，也可以作为子代理集成到如Claude Code等平台中。

入门指南

按照以下步骤操作，即可启动并运行Gmail MCP代理。

先决条件

Python 3.8或更高版本

pip 并且 virtualenv

一个已启用Gmail的Google账户

访问 Google Cloud Console

来自Google AI Studio的Gemini API密钥

安装
克隆仓库：
git clone <repository-url>
cd gmail-mcp-agent
创建并激活虚拟环境：
python3 -m venv venv
source venv/bin/activate
安装所需的依赖项：
pip install -r requirements.txt

配置与身份验证

此代理需要安全凭证才能访问Google服务。请仔细按照以下步骤操作。

1. Gmail API 凭据

您需要通过创建OAuth 2.0客户端ID来授权该应用程序访问Gmail数据。

前往 Google 云控制台。

创建一个新项目或选择一个现有项目。

导航至 APIs 和服务 > 已启用的 APIs 和服务 并点击 + 启用API和服务搜索“Gmail API”并启用它。

首选 APIs 和服务 > 凭据。

点击 + 创建凭据 并选择 OAuth 客户端 ID。

选择 桌面应用程序 作为申请类型。

给它起个名字（例如，“Gmail MCP 代理”）。

点击创造一个窗口将会弹出，显示您的客户端ID和客户端密钥。点击 下载JSON文件。

至关重要的是将下载的文件重命名为 client_secret.json 并将其移动到 private/ 此项目中的目录。

2. Gemini API密钥

该代理利用Gemini模型来实现其认知能力。

首选 Google AI Studio（谷歌人工智能工作室）。

点击 创建API密钥.

复制生成的API密钥。

3. 环境设置

该项目采用了一种 .env 用于安全地管理密钥的文件。 这个文件永远不应提交到版本控制系统中。
复制示例文件：
cp .env.example .env
打开 .env 复制并粘贴您的Gemini API密钥：
# .env
GEMINI_API_KEY="your_gemini_api_key_here"
4. 首次认证（OAuth 2.0）

当你第一次运行服务器时，它会需要你的许可才能访问你的Gmail账户。

认证过程是 全自动化 并且在Linux和Windows环境中均可运行：

对于WSL/Windows用户：

服务器自动检测到您正在使用WSL（Windows Subsystem for Linux）运行

它使用PowerShell在您的默认Windows浏览器中打开身份验证URL

在自动打开的浏览器中完成身份验证

对于原生Linux用户：

服务器检测到您正在原生Linux环境中运行

它会在您的默认Linux浏览器（如Firefox、Chrome等）中自动打开身份验证URL

在自动打开的浏览器中完成身份验证

认证步骤：

运行服务器（参见用法在......下面

您的浏览器应会自动打开并显示认证页面

登录你希望代理访问的谷歌账户。

您将看到一个同意屏幕，要求您“查看您的电子邮件信息和设置”的权限。请点击允许.

如果你看到“Google未验证此应用”的警告，请点击高级然后 **前往（不安全区域）**这在本地桌面应用程序中是预期的行为。

您批准后，认证流程将完成，服务器将创建一个 private/token.json 文件。此文件将用于所有未来的身份验证，因此您只需执行一次此操作。

如果浏览器没有自动打开：

WSL 用户： 控制台将显示URL - 请手动将其复制到您的Windows浏览器中

Linux 用户： 控制台将显示URL - 手动将其复制到您的浏览器中

使用方法

运行服务器

要启动代理，请从项目根目录运行主服务器脚本：
python3 src/gmail_mcp_server.py
服务器将进行初始化，如果是首次运行，它将引导您完成身份验证过程。一旦运行起来，它将监听来自已连接客户端（如 Claude CLI）的请求。

与Claude CLI的集成

这个代理被设计为在Claude CLI/Code中作为子代理使用。请按照以下详细步骤进行集成。

步骤1：安装Claude CLI

对于 macOS/Linux：
npm install -g @anthropic-ai/claude-cli
# Or via Homebrew (macOS)
brew install anthropic-ai/tap/claude-cli
对于Windows：
npm install -g @anthropic-ai/claude-cli
验证安装：
claude --version
步骤2：为MCP配置Claude CLI
创建或编辑 Claude CLI 配置文件：
mkdir -p ~/.config/claude-cli
nano ~/.config/claude-cli/config.json
添加MCP服务器配置：
{
  "apiKey": "your_anthropic_api_key",
  "mcpServers": {
    "gmail-extractor": {
      "command": "python3",
      "args": [
        "/absolute/path/to/gmail-mcp-agent/src/gmail_mcp_server.py"
      ]
    }
  }
}
重要提示： 替换 /absolute/path/to/gmail-mcp-agent/ 使用您项目目录的实际完整路径。

获取绝对路径：
cd ~/gmail-mcp-agent && pwd
备选方案：使用提供的配置模板：
cp config/claude-cli-config.json ~/.config/claude-cli/config.json
# Then edit the file to replace placeholder paths
步骤3：创建代理定义
创建代理目录：
mkdir -p ~/.config/claude-cli/agents
复制代理定义文件：
cp examples/gmail-extractor-agent.md ~/.config/claude-cli/agents/
或者手动创建它：
nano ~/.config/claude-cli/agents/gmail-extractor.md
并将内容从（某处）粘贴过来 examples/gmail-extractor-agent.md。
步骤4：验证代理注册
claude agents list
你应该看到 gmail-extractor 在可用代理列表中。

第五步：使用代理

启动一个 Claude CLI 会话：
claude
然后使用自然语言命令调用代理：

示例1：按标签提取
/agent use gmail-extractor to fetch emails with the label "work-reports" from the last 7 days
示例2：按日期范围提取
/agent use gmail-extractor to fetch emails from 2025-09-01 to 2025-10-20
示例3：使用自定义文件名进行提取
/agent use gmail-extractor to fetch emails with the label "Invoices" and save to invoices_q3.csv
示例输出：
{
  "success": true,
  "count": 15,
  "message": "Successfully exported 15 emails",
  "output_file": "csv/work-reports_emails_20251020_153000.csv"
}
故障排除

问题：“未找到代理”

验证代理定义文件是否存在： ls ~/.config/claude-cli/agents/gmail-extractor.md

检查文件权限： chmod 644 ~/.config/claude-cli/agents/gmail-extractor.md

重启 Claude CLI

问题：“MCP 服务器启动失败”

验证Python路径： which python3

手动测试服务器： python3 src/gmail_mcp_server.py

检查所有环境变量是否已设置 .env

问题：“认证失败”

删除旧令牌： rm private/token.json

手动运行服务器以完成OAuth流程

验证Gmail API凭据是否存在： ls private/client_secret_*.json

如需完整的集成指南，请参阅： docs/CLAUDE_CLI_INTEGRATION.md 翻译为中文是：docs/CLAUDE_CLI_集成指南.md（或“CLAUDE CLI 集成文档.md”，具体翻译可能根据上下文调整，但核心意思是“CLAUDE CLI 集成相关的文档”）

运行测试

包含一个全面的测试套件，以确保代理正常运行。测试涵盖了认证逻辑、电子邮件解析、CSV文件生成以及Unicode字符处理。

要运行测试，请执行 pytest 从项目根目录开始：
pytest -v
所有测试都应通过，以确认您的环境设置正确且代理行为符合预期。

安全考虑事项

API密钥： 你的 GEMINI_API_KEY 非常敏感。该 .env 文件包含在 .gitignore 以防止它意外地被提交到版本控制系统中。 切勿分享此文件或将它提交到公共仓库。

OAuth令牌： 这个（或“该”） private/token.json 文件中包含用于访问您的Gmail帐户的OAuth 2.0令牌。它也包含在 .gitignore把这个文件当作密码来对待。

范围： 该代理仅请求 gmail.readonly 范围。这意味着它可以读取你的电子邮件，但不能发送、删除或修改它们，以将潜在风险降至最低。

许可证

这个项目采用MIT许可证授权。请参阅 LICENSE 文件中有详细信息。

使用说明

Gmail MCP 代理：一个用于电子邮件自动化的智能子代理

概述

目录

建筑学

主要特点

入门指南

先决条件

安装

配置与身份验证

1. Gmail API 凭据

2. Gemini API密钥

3. 环境设置

4. 首次认证（OAuth 2.0）

对于WSL/Windows用户：

对于原生Linux用户：

认证步骤：

使用方法

运行服务器

与Claude CLI的集成

步骤1：安装Claude CLI

步骤2：为MCP配置Claude CLI

步骤3：创建代理定义

步骤4：验证代理注册

第五步：使用代理

故障排除

运行测试

安全考虑事项

许可证

相关 MCP

Flomo笔记服务

3D资产生成服务

文档搜索服务

Microsoft 365命令行管理服务器

AI文本人性化服务

APISIX MCP服务器