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