🤖 Gmail MCP Agent - 24/7 Lead Nurturing System
A comprehensive, enterprise-grade lead nurturing system that automates Gmail outreach campaigns with intelligent follow-ups, response tracking, and 24/7 operation via MCP (Model Context Protocol) server.
🚀 Features
✅ Automated Lead Nurturing
- 24/7 Operation - Runs continuously with Docker containerization
- Intelligent Follow-ups - Automatic sequences at 3 days and 7 days
- Response Tracking - Monitors Gmail for replies and categorizes them
- Lead Scoring - Tracks engagement and interest levels
- Smart Responses - Automatically responds to interested leads
📊 MCP Server Architecture
- Remote Control - Control system via MCP protocol
- Real-time Monitoring - Live status and performance tracking
- Docker Deployment - Production-ready containerization
- Health Checks - Automatic recovery and error handling
- Scalable Design - Ready for enterprise use
🎯 Email Campaign Management
- CSV-based Lead Lists - Easy contact management
- Template System - Jinja2-powered email personalization
- Rate Limiting - Respects Gmail API quotas
- Resume Capability - Continue from where you left off
- Comprehensive Logging - Complete audit trail
📁 Project Structure
├── send_from_csv.py # Main Gmail sender script
├── lead_nurturer.py # Automated nurturing system
├── mcp_server.py # 24/7 MCP server
├── mcp_client.py # Control interface
├── lead_dashboard.py # Monitoring dashboard
├── run_nurturing.py # Automation runner
├── contacts.csv # Lead database (96 dental practices)
├── body.txt # Email template
├── credentials.json # Gmail API credentials
├── nurturing_config.json # System configuration
├── gmail_sync_state.json # Gmail incremental sync state (auto-created)
├── requirements.txt # Python dependencies
├── Dockerfile # Container configuration
├── docker-compose.yml # Deployment setup
├── deploy.sh # One-click deployment
└── DEPLOYMENT_GUIDE.md # Complete setup guide
🛠️ Quick Start
1. Clone and Setup
git clone https://github.com/brandononchain/GMAIL-MCP-Agent.git
cd GMAIL-MCP-Agent
pip install -r requirements.txt
2. Configure Gmail API
- Get OAuth2 credentials from Google Cloud Console
- Save as
credentials.json - Update sender email in
nurturing_config.json
3. Deploy 24/7 System
# Docker deployment (recommended)
./deploy.sh
# Or manual deployment
docker-compose up -d
4. Start Nurturing
# Using MCP client
python mcp_client.py start 4
# Or direct execution
python run_nurturing.py
🎮 Control Commands
MCP Client Interface
# Start nurturing system (every 4 hours)
python mcp_client.py start 4
# Check system status
python mcp_client.py status
# Get lead report
python mcp_client.py report
# Send test email
python mcp_client.py test your-email@example.com
# View recent logs
python mcp_client.py logs 100
# Stop the system
python mcp_client.py stop
Direct Scripts
# Run single nurturing cycle
python lead_nurturer.py
# View lead dashboard
python lead_dashboard.py
# Send emails from CSV
python send_from_csv.py contacts.csv --body_file body.txt
📊 Current Campaign
Dental Practice Outreach
- Target: 96 dental practices in Chicago
- Message: AI lead follow-up system for dental practices
- Follow-up Schedule: 3 days and 7 days after initial contact
- Expected Results: 20-30% response rate, 10-15% conversion
Email Template
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
🔧 Configuration
Environment Variables
# Gmail API Configuration
CREDENTIALS_FILE=credentials.json
TOKEN_FILE=token.json
# Nurturing Settings
PER_MINUTE=12
RESUME=false
LOG_FILE=send_log.csv
# MCP Server Settings
MCP_SERVER_PORT=8000
LOG_LEVEL=INFO
Nurturing Configuration
{
"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
}
}
📈 Performance Metrics
Expected Results
- Response Rate: 20-30% from initial outreach
- Follow-up Response: 40-60% from follow-ups
- Conversion Rate: 10-15% to interested leads
- Automation Coverage: 80% of responses handled automatically
- Uptime: 99.9% with Docker restart policies
Monitoring
- Real-time lead scoring and status tracking
- Response rate analytics and conversion metrics
- System health monitoring and error reporting
- Complete audit trail of all interactions
🚀 Deployment Options
Docker (Recommended)
# One-click deployment
./deploy.sh
# Manual deployment
docker-compose up -d
Local Development
# Install dependencies
pip install -r requirements.txt
# Run nurturing system
python run_nurturing.py
Production Server
# Systemd service
sudo cp lead-nurturing.service /etc/systemd/system/
sudo systemctl enable lead-nurturing
sudo systemctl start lead-nurturing
🔒 Security & Privacy
- Local Data Storage - All data remains on your server
- OAuth2 Authentication - Secure Gmail API access
- No External Services - No data sent to third parties
- Encrypted Credentials - Secure credential management
- Audit Logging - Complete activity tracking
📞 Support & Documentation
- Deployment Guide:
DEPLOYMENT_GUIDE.md - Nurturing Guide:
NURTURING_README.md - Debug Report:
DEBUG_REPORT.md - Docker Setup:
docker-compose.yml
🎯 Use Cases
Sales Outreach
- B2B lead generation and nurturing
- Automated follow-up sequences
- Response tracking and lead scoring
Marketing Campaigns
- Email marketing automation
- A/B testing and optimization
- Performance analytics
Customer Success
- Onboarding email sequences
- Renewal and upsell campaigns
- Customer feedback collection
📊 System Architecture
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ MCP Client │◄──►│ MCP Server │◄──►│ Lead Nurturer │
│ (Control) │ │ (24/7 Service) │ │ (Automation) │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│
▼
┌──────────────────┐
│ Gmail API │
│ (Email System) │
└──────────────────┘
🏆 Enterprise Features
- 24/7 Operation - Continuous automation
- Scalable Architecture - Handle thousands of leads
- Professional Monitoring - Real-time dashboards
- Error Recovery - Automatic failure handling
- Audit Compliance - Complete activity logging
- Docker Deployment - Production-ready containerization
Ready to automate your lead nurturing? 🚀
This system is production-ready and can handle enterprise-scale email campaigns with full automation, monitoring, and 24/7 operation.
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
📧 Contact
- Author: Brandon
- Company: Quantra Labs
- Repository: GMAIL-MCP-Agent