smart-email-mcp

sandeepkmishra01-glitch/smart-email-mcp

3.1

If you are the rightful owner of smart-email-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

Smart Email MCP Server is a robust Model Context Protocol server designed for intelligent email processing and seamless Telegram integration, utilizing OAuth authentication for secure Gmail account access.

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