sandeepkmishra01-glitch/smart-email-mcp

Smart Email MCP Server

A powerful Model Context Protocol (MCP) server that provides intelligent email processing and Telegram integration with OAuth authentication for Gmail accounts.

🌟 Features

• 📧 Multi-Account Email Monitoring: Monitor multiple Gmail accounts simultaneously
• 🤖 Telegram Bot Integration: Interact with your emails via Telegram commands
• 🔐 OAuth 2.0 Authentication: Secure authentication for Gmail accounts
• 🌐 Web Interface: Beautiful web dashboard for email management
• 📊 Real-time Notifications: Get instant notifications for new emails
• 🔍 Smart Email Processing: Intelligent email filtering and categorization
• 📱 Mobile-Friendly: Responsive design for mobile devices

🚀 Quick Start

Prerequisites

• Python 3.8 or higher
• Gmail accounts with OAuth 2.0 enabled
• Telegram Bot Token

Installation

1. Clone the repository

   git clone https://github.com/yourusername/smart-email-mcp.git
   cd smart-email-mcp
   

2. Install dependencies

   cd mcp-server
   pip install -r requirements.txt
   

3. Configure OAuth credentials

   • Set up Google Cloud Console project
   • Enable Gmail API
   • Create OAuth 2.0 credentials
   • Download credentials.json to mcp-server/ directory

4. Set up environment variables

   cp env.example .env
   # Edit .env with your configuration
   

5. Run OAuth setup

   python multi_oauth_setup.py
   

6. Start the MCP server

   python run_mcp_server.py
   

📁 Project Structure

smart-email-mcp/
├── mcp-server/                 # Main application directory
│   ├── src/                   # Source code
│   │   ├── mcp_server.py      # Main MCP server
│   │   ├── email_utils/       # Email processing utilities
│   │   ├── telegram_bot/      # Telegram bot implementation
│   │   └── subagents/         # MCP subagents
│   ├── config/                # Configuration files
│   ├── data/                  # Data storage
│   ├── logs/                  # Application logs
│   ├── requirements.txt       # Python dependencies
│   ├── .env                   # Environment variables
│   └── run_mcp_server.py      # Standard MCP server startup
├── .gitignore                 # Git ignore rules
├── README.md                  # This file
└── start_mcp_server.bat       # Windows startup script

🔧 Configuration

Environment Variables (.env)

# Telegram Bot Configuration
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
TELEGRAM_CHAT_ID=your_chat_id

# Gmail OAuth Configuration
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REDIRECT_URI=http://localhost:8080/callback

# Server Configuration
HOST=localhost
PORT=8000
DEBUG=True

# Email Configuration
EMAIL_CHECK_INTERVAL=300  # 5 minutes
MAX_EMAILS_PER_CHECK=50

OAuth Setup

1. Google Cloud Console Setup

   • Create a new project
   • Enable Gmail API
   • Create OAuth 2.0 credentials
   • Add authorized redirect URIs

2. Run OAuth Authentication

   python multi_oauth_setup.py
   

   This will:

   • Authenticate your personal Gmail account
   • Authenticate your Georgetown email account
   • Generate OAuth tokens

🤖 Telegram Bot Commands

Once the server is running, you can interact with your emails via Telegram:

• /start - Initialize the bot
• /help - Show available commands
• /status - Check server status
• /emails - Get recent emails
• /search <query> - Search emails
• /monitor - Toggle email monitoring
• /settings - Configure preferences

🌐 Web Interface

Access the web interface at http://localhost:8000 to:

• View email dashboard
• Manage email accounts
• Configure settings
• View system logs
• Monitor server status

📊 MCP Protocol Features

This server implements the Model Context Protocol (MCP) with:

• Standard HTTP responses (200 OK)
• Persistent connections
• Regular polling intervals
• Graceful error handling
• Process monitoring
• Comprehensive logging

🔒 Security Features

• OAuth 2.0 Authentication: Secure Gmail access
• Environment Variables: Sensitive data protection
• Token Management: Automatic token refresh
• Input Validation: Secure command processing
• Error Handling: Graceful failure management

🛠️ Development

Running in Development Mode

cd mcp-server
python run_mcp_server.py

Running with Standard Protocol

cd mcp-server
python run_mcp_server.py

Windows Quick Start

Double-click start_mcp_server.bat or run:

start_mcp_server.bat

📝 Logging

The application provides comprehensive logging:

• Application Logs: mcp_server.log
• Email Processing: Real-time email monitoring logs
• Telegram Bot: Bot interaction logs
• Error Tracking: Detailed error information

🔧 Troubleshooting

Common Issues

1. OAuth Authentication Failed

   • Verify Google Cloud Console setup
   • Check credentials.json file
   • Ensure redirect URI is correct

2. Telegram Bot Not Responding

   • Verify bot token in .env
   • Check internet connection
   • Ensure bot is not blocked

3. Email Not Being Monitored

   • Check OAuth tokens are valid
   • Verify Gmail API is enabled
   • Check email check interval settings

Debug Mode

Enable debug mode in .env:

DEBUG=True

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📞 Support

For support and questions:

• Create an issue on GitHub
• Check the troubleshooting section
• Review the logs for error details

🔄 Updates

To update the application:

git pull origin main
pip install -r requirements.txt
python run_mcp_server.py

Built with ❤️ for intelligent email management