Gmail AI 助手系统 - 完整设置指南
一个完整的双组件系统，通过由安全本地服务器支持的人工智能代理，使用自然语言查询Gmail。
MCP Server Start *图1：MCP服务器启动并准备好接受连接*
______________________________________________________________________
📋 目录
______________________________________________________________________
系统概述
该系统由两个主要组件协同工作组成：
组件1：MCP服务器 (模型上下文协议服务器)
- 在本地运行的安全Web服务器
localhost:8000 - 管理Gmail API OAuth2身份验证
- 处理凭证存储和令牌刷新
- 提供用于获取电子邮件的REST API
- 永远不要向代理暴露凭证
组件2：Gmail代理
- 面向用户的对话式人工智能界面
- 自然语言查询处理
- 丰富的终端显示，支持格式化表格
- 通过HTTP与MCP服务器通信
- 安全 - 从不处理OAuth凭证
为何选择这种架构？
安全OAuth凭据在MCP服务器中是隔离的。代理永远不会看到令牌或密钥。
模块化组件可以独立进行开发、测试和维护。
可扩展性多个代理可以连接到一个MCP服务器（未来将增强此功能）。
______________________________________________________________________
建筑
系统流程
┌─────────────────────────────────────────────────────────────────────┐
│ USER │
│ (Terminal Interface) │
└────────────────────────────┬────────────────────────────────────────┘
│
│ Natural Language Query
│ "Show me emails from john@example.com"
▼
┌─────────────────────────────────────────────────────────────────────┐
│ GMAIL AGENT │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Query │→ │ MCP │→ │ Display │ │
│ │ Parser │ │ Client │ │ Module │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└────────────────────────────┬────────────────────────────────────────┘
│
│ HTTP POST /fetch-emails
│ {"sender": "john@example.com", ...}
▼
┌─────────────────────────────────────────────────────────────────────┐
│ MCP SERVER │
│ (localhost:8000) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ OAuth2 │→ │ Gmail │→ │ Credential │ │
│ │ Handler │ │ Service │ │ Manager │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└────────────────────────────┬────────────────────────────────────────┘
│
│ Gmail API v1 (authenticated)
▼
┌─────────────────────────────────────────────────────────────────────┐
│ GMAIL API │
│ (Google Cloud) │
└─────────────────────────────────────────────────────────────────────┘数据流示例
- 用户“给我看看昨天的邮件”
- 代理解析查询 →
{date_range: {start: "2024-10-22", end: "2024-10-23"}} - 代理 → MCP（管理控制协议/多协议控制器，具体含义需根据上下文确定）：
POST /fetch-emails带有解析后的参数 - MCP服务器构建Gmail查询语句 →
after:2024/10/22 before:2024/10/23 - MCP → Gmail API经过认证的消息请求
- Gmail API → MCP返回带有元数据的电子邮件列表
- MCP → 代理格式化的JSON响应
- 代理 → 用户带有结果的漂亮表格
______________________________________________________________________
先决条件
所需软件
- Python 3.8或更高版本
- 互联网连接 （用于Gmail API访问）
- 网络浏览器 （用于OAuth认证）
Google Cloud 设置
- 带有Gmail的Google账户
- Google 云项目（免费套餐）
- Gmail API已启用
- 下载的OAuth 2.0凭证
系统要求
- 操作系统（Operating System）Windows、macOS 或 Linux
- RAM（随机存取存储器）最低512MB
- 磁盘100MB可用空间
______________________________________________________________________
快速入门指南
步骤1：设置Google Cloud（10分钟）
1.1 创建Google云项目
- 首选 Google Cloud 控制台
- 点击“新建项目”
- 名称：“Gmail AI 助手”
- 点击“创建”
1.2 启用 Gmail API
- 在你的项目中，转到 API（应用程序编程接口）和服务 → 图书馆
- 搜索“Gmail API”
- 点击“Gmail API”→ 点击“启用”
1.3 创建OAuth凭据
- 首选 APIs（应用程序编程接口）和服务 → 凭证；资格；资历
- 点击“创建凭据”→“OAuth 客户端 ID”
- 配置同意屏幕 （如提示时）：
- 用户类型： 外部的 - 应用名称：“Gmail AI 助手” - 用户支持邮箱：您的邮箱 - 开发者联系方式：您的电子邮件 - 点击“保存并继续” - 范围：暂不处理 - 测试用户： 添加您的Gmail地址 - 点击“保存并继续”
- 创建OAuth客户端：
- 申请类型： 桌面应用程序 - 名称：“Gmail 助理客户端” - 点击“创建”
- 下载JSON文件
- 重命名为
client_secret_xxx.json
步骤2：设置MCP服务器（5分钟）
# Navigate to MCP server directory
cd mcp-server
# Run setup script
# Windows:
setup.bat
# macOS/Linux:
chmod +x setup.sh && ./setup.sh
# Place OAuth credentials
# Move downloaded client_secret_xxx.json to Pri/ folder
mkdir Pri
move Downloads\client_secret_*.json Pri\ # Windows
# or
mv ~/Downloads/client_secret_*.json Pri/ # macOS/Linux步骤3：验证MCP服务器（2分钟）
# Start MCP server
python main.py你应该看到：
INFO: Uvicorn running on http://127.0.0.1:8000使用手动方法进行身份验证：
打开一个 新航站楼 窗口运行：
# In mcp-server directory
python manual_auth.py这将：
- 自动打开您的浏览器
- 显示Google OAuth授权屏幕
- 授权访问后保存凭据
After Authentication *图2：已成功使用Gmail进行身份验证*
验证身份：
curl http://localhost:8000/auth/status应显示： "authenticated": true
步骤4：设置Gmail代理（3分钟）
打开一个新的终端 （保持MCP服务器运行）
# Navigate to agent directory
cd gmail-agent
# Run setup script
# Windows:
setup.bat
# macOS/Linux:
chmod +x setup.sh && ./setup.sh
# Create .env file (optional - defaults work)
cp .env.example .env步骤5：运行代理（1分钟）
# In gmail-agent directory
python main.pyClient Works *图3：Gmail代理准备接受查询*
你会看到问候语，然后就可以开始查询了！
步骤6：尝试您的第一个查询
[Query] > Show me emails from yesterdayAnswers from the client *图4：代理以格式化表格显示查询结果*
______________________________________________________________________
组件1：MCP服务器
概述
MCP服务器是一个基于FastAPI的网络服务器，负责处理所有Gmail API交互、OAuth认证和凭证管理。
特点/特性
✅ OAuth2 认证
- 自动刷新令牌
- 安全凭证存储
- 包含手动认证脚本
✅ Gmail API 代理
- 使用过滤器获取电子邮件
- 从参数构建查询
- 响应格式化
✅（对号，表示正确、同意或确认） 安全
- 仅限本地主机绑定
- 无凭证泄露
- 输入验证
✅ 自动生成的文档
- Swagger UI 在
/docs - ReDoc 在
/redoc
安装
cd mcp-server
# Setup (creates venv, installs dependencies)
python setup.bat # Windows
./setup.sh # macOS/Linux
# Place OAuth credentials in Pri/
mkdir Pri
# Move your client_secret_*.json file here认证
选项1：手动认证（推荐）
python manual_auth.py这会打开一个浏览器，处理OAuth认证，并自动保存令牌。
选项2：网页流程
# Start server
python main.py
# In another terminal
curl http://localhost:8000/auth/start
# Visit the auth_url in your browser配置
编辑 .env 文件（可选）：
SERVER_HOST=127.0.0.1
SERVER_PORT=8000
OAUTH2_CREDENTIALS_PATH=./Pri/client_secret_*.json
TOKEN_STORAGE_PATH=./Pri/token.json
GMAIL_MAX_RESULTS=100
LOG_LEVEL=INFOAPI 端点
| 终点 | 方法 | 描述 |
|---|---|---|
/ | GET | 服务器信息和端点列表 |
/health | GET | 健康检查 |
/auth/status | GET | 检查是否已认证 |
/auth/start | GET | 开始OAuth流程 |
/auth/callback | GET | OAuth 回调处理程序 |
/fetch-emails | POST | 使用过滤器获取电子邮件 |
/docs 交互式API文档 | ||
/redoc 替代API文档 |
运行服务器
# Method 1: Using main.py
python main.py
# Method 2: Using run script
run.bat # Windows
./run.sh # macOS/Linux
# Method 3: Using uvicorn directly
uvicorn main:app --host 127.0.0.1 --port 8000测试
# Check health
curl http://localhost:8000/health
# Check auth status
curl http://localhost:8000/auth/status
# Fetch emails
curl -X POST http://localhost:8000/fetch-emails \
-H "Content-Type: application/json" \
-d '{
"max_results": 5
}'项目结构
mcp-server/
├── main.py # FastAPI entry point
├── manual_auth.py # Manual authentication script
├── requirements.txt # Python dependencies
├── app/
│ ├── auth.py # OAuth2 handler
│ ├── gmail_service.py # Gmail API wrapper
│ ├── models.py # Pydantic models
│ ├── routers.py # API endpoints
│ ├── config.py # Configuration
│ └── utils.py # Utilities
├── Pri/ # Credentials (git-ignored)
│ ├── client_secret_*.json
│ └── token.json
└── logs/ # Server logs解决MCP服务器问题
“未找到OAuth2凭证文件”
- 确保
client_secret_*.json在……中Pri/文件夹 - 检查文件名是否以...开头
client_secret_
“缺少必需参数：scope”错误
- 解决方案使用
python manual_auth.py相反 - 见：
OAUTH_QUICK_FIX.md详情如下
服务器无法启动
- 检查Python版本：
python --version（需要3.8及以上版本） - 首先激活虚拟环境
- 安装依赖项：
pip install -r requirements.txt
______________________________________________________________________
组件2：Gmail代理
概述
Gmail Agent 是一款对话式人工智能，它能将自然语言查询转化为Gmail搜索，并以美观的格式化表格展示搜索结果。
特点/功能
✅ 自然语言处理
- 发送者提取（电子邮件和姓名）
- 关键词搜索
- 日期解析（相对和绝对）
- 组合查询
✅ 丰富的显示效果
- 彩色编码表格
- 格式化的日期
- 截断的片段
- 结果数量
✅（勾选标记，表示正确、完成或确认） 交互式界面
- 持续对话
- 帮助命令
- 查询历史
- 错误引导
✅ 安全
- 没有凭证处理
- 输入验证
- 与MCP服务器进行安全通信
安装
cd gmail-agent
# Setup
python setup.bat # Windows
./setup.sh # macOS/Linux
# Configure (optional)
cp .env.example .env
# Edit .env if needed (defaults work)配置
编辑 .env 文件（可选）：
MCP_SERVER_URL=http://localhost:8000
MCP_TIMEOUT=30
LOG_LEVEL=INFO运行代理
# Method 1: Using main.py
python main.py
# Method 2: Using run script
run.bat # Windows
./run.sh # macOS/Linux查询模式
由发送者（或“发件人”）
Show me emails from john@example.com
Get emails from Sarah
Emails sent by boss@company.com通过关键词
Find emails about meeting
Show emails containing invoice
Emails regarding project status按日期
Emails from yesterday
Show me emails from last week
Get emails from the past 30 days
Between Jan 1 and Jan 31组合查询
Show me emails from john@example.com about project from last week
Find emails from boss@company.com containing report from yesterday
Get emails about meeting from the past 7 days命令
help- 以示例展示帮助quit或者exit- 退出代理Ctrl+C- 中断当前操作
项目结构
gmail-agent/
├── main.py # Entry point
├── requirements.txt # Python dependencies
├── app/
│ ├── agent.py # Main agent logic
│ ├── config.py # Configuration
│ ├── mcp_client.py # MCP HTTP client
│ ├── query_parser.py # NLP query parser
│ └── display.py # Rich display
└── tests/ # Test suite解决Gmail代理问题
“无法连接到MCP服务器”
- 检查MCP服务器正在运行吗？
curl http://localhost:8000/health- 解决方案首先启动MCP服务器：
cd mcp-server && python main.py
“需要Gmail身份验证”
- 检查MCP服务器认证状态
curl http://localhost:8000/auth/status- 解决方案使用（某种方法/工具）对MCP服务器进行身份验证
manual_auth.py
“查询解析错误”
- 解决方案用更清晰的关键词重新表述
- 示例：
- 使用 from 对于发件人：“来自 john@example.com 的电子邮件” - 使用 about 关键词：“关于会议的邮件” - 使用明确的日期：“过去7天内”
______________________________________________________________________
使用示例
示例1：简单日期查询
用户输入：
Show me emails from yesterday代理输出：
Searching for emails between 2024-10-22 and 2024-10-23
Searching your inbox...
Found 12 email(s) matching your criteria
┌────────────────────┬──────────────────────┬─────────────────────────┬──────────────────┐
│ Date │ From │ Subject │ Snippet │
├────────────────────┼──────────────────────┼─────────────────────────┼──────────────────┤
│ 2024-10-22 14:30 │ John Doe │ Project Update │ Hi team, here's..│
│ 2024-10-22 10:15 │ Sarah Smith │ Meeting Tomorrow │ Don't forget our.│
│ 2024-10-22 09:00 │ Boss │ Quarterly Review │ Please submit...│
└────────────────────┴──────────────────────┴─────────────────────────┴──────────────────┘示例2：发件人+关键词
用户输入：
Find emails from boss@company.com about budget代理输出：
Searching for emails from boss@company.com containing 'budget' between 2024-10-16 and 2024-10-23
Found 3 email(s) matching your criteria
┌────────────────────┬──────────────────────┬─────────────────────────┬──────────────────┐
│ Date │ From │ Subject │ Snippet │
├────────────────────┼──────────────────────┼─────────────────────────┼──────────────────┤
│ 2024-10-20 11:00 │ boss@company.com │ Budget Proposal 2024 │ Please review...│
│ 2024-10-18 15:30 │ boss@company.com │ Re: Budget Questions │ Thanks for ask...│
└────────────────────┴──────────────────────┴─────────────────────────┴──────────────────┘示例3：日期范围
用户输入：
Show emails from last month代理输出：
Searching for emails between 2024-09-23 and 2024-10-23
Found 147 email(s) matching your criteria (showing first 25)
[Table with 25 results...]示例4：组合复杂查询
用户输入：
Get emails from john@example.com about project status from last week代理输出：
Searching for emails from john@example.com containing 'project status' between 2024-10-16 and 2024-10-23
Found 5 email(s) matching your criteria
[Table with results...]______________________________________________________________________
截图
1. MCP服务器启动
MCP服务器初始化，加载配置，并开始监听 localhost:8000。
2. 成功认证
跑步之后 manual_auth.py凭据已保存，并且服务器已通过Gmail进行身份验证。
3. Gmail代理准备就绪
Gmail Agent 显示问候语，展示示例查询，并等待用户输入。
4. 查询结果
该代理以美观的格式表格展示电子邮件结果，包括日期、发件人、主题和摘要。
______________________________________________________________________
故障排除
常见问题
1. OAuth 认证失败
症状：
- “缺少必需的参数：scope”
- “访问被阻止：授权错误”
- “错误 400：无效请求”
解决方案：
# Use manual authentication
cd mcp-server
python manual_auth.py2. 代理无法连接到MCP服务器
症状：
- “无法连接到MCP服务器”
- “连接被拒绝”
检查：
# Is MCP server running?
curl http://localhost:8000/health解决方案：
# Start MCP server in separate terminal
cd mcp-server
python main.py3. “需要Gmail身份验证”
检查：
curl http://localhost:8000/auth/status解决方案：
cd mcp-server
python manual_auth.py4. 未找到结果
可能原因：
- 日期范围太窄
- 发送方的电子邮件地址拼写错误
- 关键词未匹配到任何电子邮件
解决方案：
- 扩大日期范围：“过去30天”而非“昨天”
- 检查发件人邮箱拼写
- 尝试不同的关键词
- 移除一些过滤器
5. 导入错误
症状：
- “ModuleNotFoundError”（模块未找到错误）
- “没有名为 'fastapi' 的模块”
解决方案：
# Make sure virtual environment is activated
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate
# Reinstall dependencies
pip install -r requirements.txt寻求帮助
- 检查日志：
# MCP Server logs
tail -f mcp-server/logs/mcp_server.log
# Gmail Agent logs
tail -f gmail-agent/logs/agent.log- 验证设置：
# Check Python version
python --version # Should be 3.8+
# Check virtual environment
which python # Should point to venv/bin/python
# Check MCP server health
curl http://localhost:8000/health
# Check authentication
curl http://localhost:8000/auth/status- 文档：
- MCP 服务器： mcp-server/README.md（文件名，可译为“mcp服务器/README.md”或保持原样，因为文件名通常不翻译，但为符合中文语境，可稍作解释性翻译） - Gmail 代理： gmail-agent/README.md（文件名，可译为“gmail代理/README.md”或保持原样，因为文件名通常不翻译） - OAuth 修复： mcp-server/OAUTH_QUICK_FIX.md 翻译为中文是：“mcp-server/OAUTH 快速修复指南.md” 或者更简洁地 “mcp-server/OAUTH 快速修复文件.md”
______________________________________________________________________
API 参考
MCP服务器API
POST /获取邮件
使用过滤器从Gmail中获取电子邮件。
请求：
{
"sender": "john@example.com", // Optional
"keywords": "meeting", // Optional
"date_range": { // Optional
"start": "2024-01-01", // YYYY-MM-DD
"end": "2024-01-31" // YYYY-MM-DD
},
"max_results": 50 // Optional, 1-100
}回答：
{
"emails": [
{
"id": "msg_123",
"date": "2024-01-15T09:30:00Z",
"from": "john@example.com",
"from_name": "John Doe",
"subject": "Team Meeting",
"snippet": "Hi team, reminder about..."
}
],
"total_count": 25,
"returned_count": 25
}GET /auth/status 翻译为中文是：“获取/认证/状态”
检查身份验证状态。
回答：
{
"authenticated": true,
"email": "user@gmail.com",
"scopes": ["https://www.googleapis.com/auth/gmail.readonly"],
"token_expires_at": "2024-10-23T12:00:00Z"
}获取 /health（健康检查）
服务器健康检查。
回答：
{
"status": "ok",
"version": "1.0.0",
"timestamp": "2024-10-23T10:30:00Z"
}查询解析器
代理的查询解析器支持以下模式：
发送者提取：
- 电子邮件地址：
john@example.com - 名字：
from John，from Sarah - 模式/图案：
sent by，emails by
关键词提取：
- 指标：
about，containing，regarding，with - 引述：
"project update"
日期解析：
- 相对的；相关的
yesterday，today，last week，past 30 days - 绝对值
2024-01-15，Jan 15，January 15, 2024 - 范围：
between Jan 1 and Jan 31
______________________________________________________________________
系统要求
最低要求
- CPU（中央处理器）1 GHz 单核
- RAM（随机存取存储器）512 MB
- 磁盘100 MB 空闲空间
- 网络网络连接
建议要求
- 中央处理器（CPU）2 GHz 双核或更高配置
- 随机存取存储器（RAM）1GB或以上
- 磁盘500 MB 空闲空间
- 网络宽带连接
测试平台
- ✅ Windows 10/11
- ✅ macOS 11及以上版本
- ✅ Linux（Ubuntu 20.04+，Debian 11+）
______________________________________________________________________
演出
MCP 服务器
- 初创企业\<5秒
- 健康检查\<10毫秒
- 认证状态小于50毫秒
- 获取电子邮件（10封）1-2秒
- 获取电子邮件（50封）2到4秒
- 内存约80-100MB
Gmail 代理
- 初创企业小于2秒
- 查询解析小于10毫秒
- 显示渲染\<100毫秒
- 内存~50MB（约50兆字节）
______________________________________________________________________
安全
凭证保护
- ✅ OAuth令牌存储在
Pri/文件夹（已忽略在 Git 中） - ✅ 文件权限：600（所有者仅读/写）
- ✅ 在API响应或日志中从不暴露
- ✅ 自动刷新令牌
网络安全
- ✅ MCP服务器仅绑定到
127.0.0.1(本地主机) - ✅ 无法从网络访问
- ✅ CORS 限制为本地主机（localhost）
- ✅ 代理仅与本地主机的MCP服务器通信
输入验证
- ✅ Pydantic 模型验证
- ✅ 日期格式检查
- ✅ 邮件验证
- ✅ 防止SQL注入
______________________________________________________________________
发展
运行测试
MCP 服务器：
cd mcp-server
pytest tests/ -v
pytest --cov=app tests/ # With coverageGmail 代理：
cd gmail-agent
pytest tests/ -v
pytest --cov=app tests/ # With coverage代码结构
两个组件都遵循了整洁架构原则：
- 关注点分离每个模块都有单一职责
- 依赖注入易于测试和更换部件
- 配置驱动行为可通过.env文件自定义
- 错误隔离捕获错误并转换为用户友好的消息
添加功能
添加新的查询模式 （代理）：
- 编辑
gmail-agent/app/query_parser.py - 添加正则表达式模式到
RELATIVE_DATE_PATTERNS或类似（的） - 更新
_extract_*方法 - 在其中添加测试
tests/test_query_parser.py
添加新的API端点 (服务器)：
- 添加路由到
mcp-server/app/routers.py - 在（某个地方/某个上下文中）创建 Pydantic 模型
app/models.py - 在适当的服务中添加业务逻辑
- 添加测试到
tests/
______________________________________________________________________
许可证
教育项目 - 有关许可的信息，请参阅课程材料。
______________________________________________________________________
支持
文档
- MCP 服务器： mcp-server/README.md 翻译为中文是：mcp-server/README文件（或：mcp服务器/说明文件）
- Gmail 代理： gmail-agent/README.md
- MCP 快速入门： mcp-server/QUICKSTART.md 翻译为中文是：mcp-server/快速入门指南.md
- 代理快速入门： gmail-agent/快速入门指南.md
故障排除指南
- OAuth问题： mcp-server/OAUTH_QUICK_FIX.md 翻译为中文是：mcp-server/OAUTH 快速修复指南.md
- 详细的OAuth信息： mcp-server/TROUBLESHOOTING_OAUTH.md 翻译为中文是：\
mcp-server/故障排除_OAUTH指南.md\或者更自然的表达可能是 \mcp-server/OAuth故障排查指南.md\
常用命令
启动所有程序：
# Terminal 1: MCP Server
cd mcp-server
python main.py
# Terminal 2: Gmail Agent
cd gmail-agent
python main.py检查状态：
# MCP Server
curl http://localhost:8000/health
curl http://localhost:8000/auth/status
# From Agent
Type: help日志：
# MCP Server
tail -f mcp-server/logs/mcp_server.log
# Gmail Agent
tail -f gmail-agent/logs/agent.log______________________________________________________________________
致谢
所用技术：
- FastAPI - 现代Python网络框架
- 谷歌API客户端 官方Gmail API库
- Rich（里奇/里克/瑞奇等，根据具体语境和人名习惯可有多种译法） - 精美的终端格式化
- Pydantic - 数据验证
- Uvicorn（通常指一个用于构建异步ASGI服务器的Python库，可直接翻译为“UVicorn”，但在此保持原样以体现其作为专有名词的特性） - ASGI服务器
- Python-dateutil（可译为“Python日期处理工具”或保持原名，根据上下文决定是否需要意译） - 日期解析
______________________________________________________________________
快速参考卡
设置（首次）
# 1. Google Cloud: Enable Gmail API, create OAuth credentials
# 2. MCP Server
cd mcp-server && python setup.bat && python manual_auth.py
# 3. Gmail Agent
cd gmail-agent && python setup.bat日常使用
# Terminal 1: Start MCP Server
cd mcp-server && python main.py
# Terminal 2: Start Agent
cd gmail-agent && python main.py示例查询
Show me emails from yesterday
Find emails from john@example.com
Get emails about meeting from last week
Emails containing invoice from past 30 days故障排除
# Authentication
python mcp-server/manual_auth.py
# Check health
curl http://localhost:8000/health
# View logs
tail -f mcp-server/logs/mcp_server.log______________________________________________________________________
系统状态✅ 准备就绪，可投入生产 版本1.0.0 最后更新时间2024年10月23日
______________________________________________________________________
🎉 你准备好了！开始用自然语言查询你的Gmail吧！ 🎉