Skip to content

gradient30/email-mcp-service

BranchesTags
 
 

Repository files navigation

MCP Email Service

License: MIT Python 3.11+ uv Tests GitHub Sponsors

A unified MCP email service supporting multi-account management with AI-powered intelligent monitoring and notifications.

New Feature: Email translation & summarization with n8n automation - automatically translate non-Chinese emails, generate summaries, and send to Feishu/Lark!

New Feature: n8n + AI Email Monitoring

Automatically monitor emails, filter important ones with AI, and send real-time notifications to your team chat!

  • AI Smart Filtering: Uses OpenAI/Claude to intelligently identify important emails
  • Multi-platform Notifications: Supports Feishu/DingTalk/WeChat Work/Slack
  • Automated Monitoring: n8n workflow runs every 5 minutes automatically
  • Deduplication: Prevents duplicate notifications
  • Production Ready: Comprehensive error handling and fallback mechanisms

Quick Start with AI Monitoring

# 1. Set up the monitoring system
python scripts/setup_n8n_monitoring.py

# 2. Configure environment variables
export FEISHU_WEBHOOK="your_webhook_url"
export OPENAI_API_KEY="your_api_key"  # Optional for AI filtering

# 3. Import n8n workflow
# Import n8n/email_monitoring_workflow.json in your n8n instance

# 4. Start monitoring!
# The system will automatically check emails every 5 minutes

Documentation: See N8N_EMAIL_MONITORING_GUIDE.md for complete setup guide.

Supported Email Providers

  • 163 Mail (mail.163.com / mail.126.com)
  • QQ Mail (mail.qq.com)
  • Gmail (mail.google.com)
  • Outlook/Hotmail
  • Custom IMAP servers

Quick Start

Option 1: Install via Smithery (Recommended)

npx -y @smithery/cli install mcp-email-service --client claude

After installation, you'll need to configure your email accounts:

cd ~/.config/smithery/servers/mcp-email-service
python setup.py

Option 2: Manual Installation

Requires Python 3.11+ and UV.

git clone https://github.com/leeguooooo/email-mcp-service.git
cd email-mcp-service
uv sync

2. Configure Email Accounts

# Interactive setup
uv run python setup.py

# Or manually copy example config
cp examples/accounts.example.json accounts.json
# Then edit accounts.json with your email settings

Email Configuration Guide

Provider Configuration Steps
163 Mail Login to mail.163.com → Settings → Enable IMAP → Get authorization code (use code, not password)
QQ Mail Settings → Account → Enable IMAP → Generate authorization code
Gmail Enable 2FA → Generate app password
Outlook Use email password directly

3. Add to MCP Client (Manual Installation Only)

If you installed manually, add to your MCP client (e.g., Claude Desktop) config:

{
    "mcpServers": {
        "mcp-email-service": {
            "command": "/your/path/mcp-email-service/run.sh",
            "args": []
        }
    }
}

Main Features

View Emails

list_emails                              # View unread emails
list_emails with unread_only=false       # View all emails
list_emails with limit=100               # View more emails

Search Emails

search_emails with query="meeting"                 # Search emails containing "meeting"
search_emails with query="john" search_in="from"   # Search by sender
search_emails with date_from="2024-01-01"         # Search by date

Email Operations

get_email_detail with email_id="123"              # View email details
mark_emails with email_ids=["123"] mark_as="read" # Mark as read
delete_emails with email_ids=["123"]              # Delete email
flag_email with email_id="123" set_flag=true      # Add star

Send Emails

send_email with to=["user@example.com"] subject="Subject" body="Content"
reply_email with email_id="123" body="Reply content"

Contact Analysis ⭐ NEW

analyze_contacts                                     # Analyze top contacts (last 30 days)
analyze_contacts with days=90 limit=20               # Customize analysis period
analyze_contacts with group_by="sender"              # Analyze only senders
get_contact_timeline with contact_email="user@example.com"  # Get communication timeline

Available Commands

Basic Email Operations

  • list_emails - List emails
  • get_email_detail - View email details
  • search_emails - Search emails
  • mark_emails - Mark as read/unread
  • delete_emails - Delete emails
  • flag_email - Star/unstar emails
  • send_email - Send new email
  • reply_email - Reply to email
  • forward_email - Forward email
  • move_emails_to_folder - Move emails
  • list_folders - View folders
  • get_email_attachments - Get attachments
  • check_connection - Test connections
  • analyze_contacts ⭐ - Analyze contact frequency
  • get_contact_timeline ⭐ - Get communication timeline

AI Monitoring System

The AI monitoring system includes several powerful scripts:

Core Scripts

  • scripts/call_email_tool.py - Bridge between n8n and MCP tools
  • scripts/ai_email_filter.py - AI-powered email importance filtering
  • scripts/notification_service.py - Multi-platform notification service
  • scripts/email_monitor.py - Main monitoring controller
  • scripts/setup_n8n_monitoring.py - Automated setup script

Usage Examples

# Test email fetching
python scripts/call_email_tool.py list_unread_emails '{"limit":5}'

# Test AI filtering
python scripts/ai_email_filter.py '[{"id":"test","subject":"Urgent meeting","from":"boss@company.com","date":"2024-01-15","body_preview":"Important project discussion..."}]'

# Test notifications
python scripts/notification_service.py test

# Run complete monitoring cycle
python scripts/email_monitor.py run

# Check system status
python scripts/email_monitor.py status

Supported Notification Platforms

  • Feishu/Lark - Rich card notifications with interactive elements
  • DingTalk - Markdown formatted messages with @mentions
  • WeChat Work - Styled messages with color coding
  • Slack - Block-based rich formatting
  • Custom Webhooks - Flexible JSON payload support

Troubleshooting

Basic Email Issues

  1. Login Failed: 163/QQ Mail use authorization codes, Gmail uses app passwords
  2. Can't Find Emails: Default shows unread only, use unread_only=false
  3. Connection Timeout: Check network and firewall settings

AI Monitoring Issues

  1. AI Filtering Failed: System automatically falls back to keyword filtering if AI API fails
  2. Webhook Not Working: Verify webhook URL and test with python scripts/test_lark_webhook.py
  3. n8n Workflow Errors: Check environment variables (FEISHU_WEBHOOK, OPENAI_API_KEY)
  4. Script Permission Denied: Run chmod +x scripts/*.py to make scripts executable
  5. No Notifications: Check notification config and test with python scripts/notification_service.py test

Quick Diagnostics

# Check system status
python scripts/email_monitor.py status

# Test all components
python scripts/setup_n8n_monitoring.py --test-only

# View logs
tail -f email_monitor.log

# Check environment variables
env | grep -E "(FEISHU|OPENAI|PYTHONPATH)"

Project Structure

mcp-email-service/
├── data/                       # Runtime data directory (auto-created)
│   ├── email_sync.db          # Email synchronization database
│   ├── sync_config.json       # Sync configuration
│   ├── logs/                  # Log files
│   ├── tmp/                   # Temporary files
│   └── attachments/           # Downloaded attachments
├── src/                       # Source code
│   ├── config/               # Configuration management
│   │   └── paths.py          # Centralized path configuration
│   ├── operations/           # Email operations
│   ├── background/           # Background sync scheduler
│   └── ...
├── tests/                     # Test suite (71/72 passing)
├── docs/                      # Documentation
│   ├── guides/               # User guides
│   └── archive/              # Historical documents
├── scripts/                   # Utility scripts
├── n8n/                      # n8n workflow templates
├── config_templates/         # Configuration examples
└── accounts.json             # Email account configuration (user-created)

Key Features

  • Auto-start Background Sync: Synchronization starts automatically with MCP server
  • Centralized Data Management: All runtime data in data/ directory
  • UID-based Operations: Stable email identification across operations
  • Smart Caching: 100-500x faster than live IMAP queries
  • Multi-account Support: Manage multiple email accounts with proper isolation
  • Performance Optimized: Shared connections for batch operations (5x faster)
  • Well Tested: 71/72 tests passing, ~65% code coverage

Documentation

Quick Start Guides

Deployment & Security

Technical Documentation

Support This Project

If you find this project helpful, please consider:

  • Star this repository to show your support
  • Report bugs or suggest features via Issues
  • Contribute code or documentation via Pull Requests
  • Sponsor the development via GitHub Sponsors

Support via WeChat Pay / Alipay

If you'd like to support this project, you can use WeChat Pay or Alipay:

WeChat Pay QR Code Alipay QR Code

Scan to support via WeChat Pay or Alipay

Your support helps maintain and improve this project! Thank you!

Contributing

We welcome contributions! Please feel free to submit issues and pull requests.

Development Setup

# Clone the repository
git clone https://github.com/leeguooooo/email-mcp-service.git
cd email-mcp-service

# Install dependencies (including dev tools)
uv sync --extra dev

# Run tests
uv run pytest

# Set up development environment
cp config_templates/env.n8n.example .env
# Edit .env with your configuration

Running Tests

# Run all tests
uv run pytest

# Run specific test file
uv run pytest tests/test_mcp_tools.py

# Run with coverage
uv run pytest --cov=src --cov-report=html

Code Quality

Option 1: Install dev dependencies (recommended)

# Install with dev extras (includes black, ruff, mypy)
uv sync --extra dev

# Then run tools
uv run black src/ scripts/ tests/
uv run ruff check src/ scripts/ tests/
uv run mypy src/

Option 2: Use uv tool (no installation needed)

# Format code
uvx black src/ scripts/ tests/

# Lint code
uvx ruff check src/ scripts/ tests/

# Type check
uvx mypy src/

Features Roadmap

  • Multi-account email management
  • AI-powered email filtering
  • Email translation & summarization (OpenAI)
  • Multi-platform notifications
  • n8n workflow automation
  • Production-ready error handling
  • Email auto-reply with AI
  • Smart email categorization
  • Advanced analytics dashboard
  • Mobile app notifications

Security

API Key Protection

All sensitive endpoints are protected with API key authentication. See SECURITY_SETUP_GUIDE.md for details.

Environment Variables

Never commit sensitive information. Always use environment variables:

  • .env files are automatically ignored by git
  • Use .env.example templates for documentation
  • Rotate API keys regularly

Reporting Security Issues

Please report security vulnerabilities to the repository maintainers privately before public disclosure.

License

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

About

使用 AI 管理您的邮件

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages

  • Python 99.4%
  • Shell 0.6%