使用说明

Gmail MCP - 基于人工智能的电子邮件助手

一个智能的Gmail客户端，它使用 MCP（模型上下文协议） 与Gmail进行交互，并 双子座AI 提供智能邮件管理功能。

🌟 特点/功能

🤖 基于人工智能的电子邮件分析 - 使用Gemini AI分析电子邮件并确定适当的行动
📧 完整的Gmail集成 通过Gmail API发送、读取、整理和管理电子邮件
🔧 MCP 协议 - 使用模型上下文协议的现代客户端-服务器架构
📊 完全透明 - 完整记录所有人工智能交互
🎯 智能操作 - 自动回复、摘要生成、垃圾邮件检测和邮件整理
💬 交互式界面 - 命令行界面，便于管理电子邮件

🏗️ 建筑

┌─────────────────┐    MCP Protocol    ┌─────────────────┐
│   talk2gmail.py │ ◄─────────────────► │  gmail/server.py │
│   (MCP Client)  │                    │  (MCP Server)   │
│                 │                    │                 │
│ • Gemini AI     │                    │ • Gmail API     │
│ • User Interface│                    │ • OAuth 2.0     │
│ • Command Parser│                    │ • Email Tools   │
└─────────────────┘                    └─────────────────┘

📦 组件

1. Gmail MCP 服务器 (`gmail/server.py`)

通过MCP工具提供Gmail API集成
处理OAuth 2.0身份验证
将电子邮件操作暴露为MCP工具

2. Gmail MCP 客户端 (`talk2gmail.py`)

连接到Gmail MCP服务器
利用Gemini AI进行智能邮件分析
提供交互式命令接口

🛠️ 可用的Gmail工具

MCP服务器提供以下电子邮件管理工具：

工具	描述	参数
`send-email`	发送电子邮件	`recipient_id`， `subject`， `message`
`get-unread-emails`	获取未读邮件	无
`read-email`	获取完整邮件内容	`email_id`
`trash-email`	将邮件移至垃圾箱	`email_id`
`mark-email-as-read`	将邮件标记为已读	`email_id`
`open-email` 在浏览器中打开邮件 `email_id`

🚀 快速入门

先决条件

Python 3.8或更高版本
紫外线 - 快速的Python包管理器（安装指南）
Google 云项目 已启用Gmail API
Gemini API密钥

安装

安装 uv（如果尚未安装）：

# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or with pip
pip install uv

克隆仓库：

git clone <repository-url>
cd gmail_mcp

使用 uv 安装依赖项：

# Install all dependencies (recommended)
uv sync

# Or install with optional enhanced features
uv sync --extra enhanced

# Or install with development dependencies
uv sync --extra dev

设置环境变量：

# Create .env file
echo "GEMINI_API_KEY=your_gemini_api_key_here" > .env

设置Gmail OAuth：
- 首选 Google 云控制台
- 启用Gmail API
- 创建OAuth 2.0凭据
- 下载凭据为 client_creds.json

首映/首次运行

uv run python talk2gmail.py

首次运行时，您将完成OAuth流程：

浏览器打开以进行谷歌认证
授予访问Gmail的权限
令牌已保存，以便将来使用

替代的uv命令

# Run with uv (recommended)
uv run python talk2gmail.py

# Or activate virtual environment and run directly
uv shell
python talk2gmail.py

💻 使用方法

示例查询

# Natural language queries
📧 Enter your Gmail request: get my unread emails
📧 Enter your Gmail request: read the latest email from john@example.com
📧 Enter your Gmail request: send a thank you email to sarah@company.com

🤖 人工智能驱动的功能

智能邮件分析

人工智能分析电子邮件并确定行动：

回复 - 生成符合上下文的回复
总结 - 创建简洁的摘要
紧急 - 标记重要邮件
垃圾邮件 - 检测并处理垃圾邮件
档案 - 整理日常邮件

示例AI分析

📧 Processing email: abc123
📖 From: client@company.com
📝 Subject: Project Update Required
🤖 AI Action: REPLY
💭 AI Reasoning: Client requesting project status - should provide update
✅ Reply sent: "Thank you for your inquiry. I'll provide the project update by end of day."

🔧 配置

环境变量

创建一个 .env 文件：

GEMINI_API_KEY=your_gemini_api_key_here

Gmail 凭证

Google Cloud Console 设置：
- 创建项目
- 启用Gmail API
- 创建OAuth 2.0凭据
- 添加授权重定向URI： http://localhost:8080
下载凭据为 client_creds.json

所需范围

该应用程序需要以下Gmail权限范围：

https://www.googleapis.com/auth/gmail.modify

📁 项目结构

gmail_mcp/
├── gmail/
│   ├── __init__.py          # Package entry point
│   └── server.py            # Gmail MCP server
├── talk2gmail.py            # Gmail MCP client
├── client_creds.json        # Gmail OAuth credentials (you provide)
├── token.json              # OAuth tokens (auto-generated)
├── .env                    # Environment variables (you create)
├── pyproject.toml          # Project configuration and dependencies
├── requirements.txt        # Python dependencies (legacy)
├── uv.lock                 # Dependency lock file (auto-generated)
└── README.md              # This file

🔐 安全

OAuth 2.0 - 通过谷歌进行安全认证
本地存储 - 令牌存储在本地，从不传输
最小范围 - 仅请求必要的Gmail权限
不收集数据 - 所有处理都在本地进行

使用MCP（模型上下文协议）和Gemini AI，满怀爱意地打造而成