Gmail MCP Agent

🚀 🤖 Gmail MCP Agent - 24/7潜在客户培育系统

这是一个全面的企业级潜在客户培育系统，通过MCP（模型上下文协议）服务器实现Gmail外展活动的自动化，具备智能跟进、回复跟踪功能，可实现全天候运行。

🚀 快速开始

1. 克隆并设置项目

git clone https://github.com/brandononchain/GMAIL-MCP-Agent.git
cd GMAIL-MCP-Agent
pip install -r requirements.txt

2. 配置Gmail API

• 从Google Cloud Console获取OAuth2凭证。
• 将其保存为credentials.json。
• 在nurturing_config.json中更新发件人邮箱。

3. 部署全天候系统

# 使用Docker部署（推荐）
./deploy.sh

# 或手动部署
docker-compose up -d

4. 开始培育潜在客户

# 使用MCP客户端
python mcp_client.py start 4

# 或直接执行
python run_nurturing.py

✨ 主要特性

✅ 自动化潜在客户培育

• 全天候运行 - 通过Docker容器化实现持续运行。
• 智能跟进 - 在第3天和第7天自动执行跟进序列。
• 回复跟踪 - 监控Gmail中的回复并进行分类。
• 潜在客户评分 - 跟踪参与度和兴趣水平。
• 智能回复 - 自动回复有兴趣的潜在客户。

📊 MCP服务器架构

• 远程控制 - 通过MCP协议控制系统。
• 实时监控 - 实时跟踪状态和性能。
• Docker部署 - 具备生产就绪的容器化能力。
• 健康检查 - 自动恢复和错误处理。
• 可扩展设计 - 适用于企业级应用。

🎯 电子邮件活动管理

• 基于CSV的潜在客户列表 - 方便的联系人管理。
• 模板系统 - 由Jinja2驱动的电子邮件个性化。
• 速率限制 - 遵守Gmail API配额。
• 恢复功能 - 可从上次中断的位置继续。
• 全面日志记录 - 完整的审计跟踪。

📦 安装指南

Docker（推荐）

# 一键部署
./deploy.sh

# 手动部署
docker-compose up -d

本地开发

# 安装依赖
pip install -r requirements.txt

# 运行培育系统
python run_nurturing.py

生产服务器

# Systemd服务
sudo cp lead-nurturing.service /etc/systemd/system/
sudo systemctl enable lead-nurturing
sudo systemctl start lead-nurturing

💻 使用示例

基础用法

MCP客户端接口

# 启动培育系统（每4小时一次）
python mcp_client.py start 4

# 检查系统状态
python mcp_client.py status

# 获取潜在客户报告
python mcp_client.py report

# 发送测试邮件
python mcp_client.py test your-email@example.com

# 查看最近的日志
python mcp_client.py logs 100

# 停止系统
python mcp_client.py stop

直接运行脚本

# 运行单次培育周期
python lead_nurturer.py

# 查看潜在客户仪表盘
python lead_dashboard.py

# 从CSV文件发送邮件
python send_from_csv.py contacts.csv --body_file body.txt

📚 详细文档

项目结构

├── send_from_csv.py          # 主要的Gmail发送脚本
├── lead_nurturer.py          # 自动化培育系统
├── mcp_server.py             # 24/7运行的MCP服务器
├── mcp_client.py             # 控制接口
├── lead_dashboard.py         # 监控仪表盘
├── run_nurturing.py          # 自动化运行器
├── contacts.csv              # 潜在客户数据库（96家牙科诊所）
├── body.txt                  # 电子邮件模板
├── credentials.json          # Gmail API凭证
├── nurturing_config.json     # 系统配置
├── gmail_sync_state.json     # Gmail增量同步状态（自动创建）
├── requirements.txt          # Python依赖项
├── Dockerfile               # 容器配置
├── docker-compose.yml       # 部署设置
├── deploy.sh                # 一键部署脚本
└── DEPLOYMENT_GUIDE.md      # 完整的设置指南

当前活动

牙科诊所外展活动

• 目标：芝加哥的96家牙科诊所。
• 信息：适用于牙科诊所的AI潜在客户跟进系统。
• 跟进时间表：首次联系后的第3天和第7天。
• 预期结果：20 - 30%的回复率，10 - 15%的转化率。

电子邮件模板

Hi {{first_name}},

Did you know many dental practices lose 20–30% of new patient inquiries because follow-ups slip through the cracks?

We've built an AI agent that automatically follows up with every lead via SMS/email and books them straight into your calendar.

Clients typically see 5–9 extra appointments in the first 30 days.

Have time for 10-min demo call this week?

Thank you,
Brandon
Quantra Labs

配置

环境变量

# Gmail API配置
CREDENTIALS_FILE=credentials.json
TOKEN_FILE=token.json

# 培育设置
PER_MINUTE=12
RESUME=false
LOG_FILE=send_log.csv

# MCP服务器设置
MCP_SERVER_PORT=8000
LOG_LEVEL=INFO

培育配置

{
  "sender_email": "your-email@domain.com",
  "follow_up_schedule": {
    "followup_1_days": 3,
    "followup_2_days": 7
  },
  "automation": {
    "check_responses_interval_hours": 4,
    "auto_respond_to_interest": true
  }
}

性能指标

预期结果

• 回复率：首次外展活动的回复率为20 - 30%。
• 跟进回复率：跟进活动的回复率为40 - 60%。
• 转化率：转化为有兴趣潜在客户的比例为10 - 15%。
• 自动化覆盖率：自动处理80%的回复。
• 正常运行时间：通过Docker重启策略实现99.9%的正常运行时间。

监控

• 实时潜在客户评分和状态跟踪。
• 回复率分析和转化指标。
• 系统健康监控和错误报告。
• 所有交互的完整审计跟踪。

使用场景

销售外展

• B2B潜在客户生成和培育。
• 自动化跟进序列。
• 回复跟踪和潜在客户评分。

营销活动

• 电子邮件营销自动化。
• A/B测试和优化。
• 性能分析。

客户成功

• 新用户入职电子邮件序列。
• 续约和追加销售活动。
• 客户反馈收集。

系统架构

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │◄──►│   MCP Server     │◄──►│  Lead Nurturer  │
│  (Control)      │    │  (24/7 Service)  │    │  (Automation)   │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌──────────────────┐
                       │   Gmail API      │
                       │  (Email System)  │
                       └──────────────────┘

企业级特性

• 全天候运行 - 持续自动化。
• 可扩展架构 - 处理数千个潜在客户。
• 专业监控 - 实时仪表盘。
• 错误恢复 - 自动故障处理。
• 审计合规 - 完整的活动日志记录。
• Docker部署 - 生产就绪的容器化。

🔧 技术细节

该系统基于Python构建，利用Gmail API实现电子邮件的发送和接收。通过MCP协议，系统可以实现远程控制和实时监控。使用Docker容器化技术，确保系统能够在不同环境下稳定运行。同时，系统还具备智能跟进、潜在客户评分和自动回复等功能，提高潜在客户培育的效率和效果。

📄 许可证

本项目采用MIT许可证 - 详情请参阅LICENSE文件。

🤝 贡献

欢迎贡献代码！请随时提交拉取请求。

📧 联系信息

• 作者：Brandon
• 公司：Quantra Labs
• 仓库：GMAIL-MCP-Agent