MCP Email Service

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 data/accounts.json
# Then edit data/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": []
        }
    }
}

4. How to Use MCP Commands

After configuration, you can use email features directly in MCP clients (like Claude Desktop):

1. Start MCP Client: Ensure the MCP service is properly configured and running

2. Use in Conversations: Request email operations directly in conversations, for example:

   • "Show me unread emails"
   • "Search for emails containing 'meeting'"
   • "Mark email 123 as read"
   • "Send email to user@example.com"

3. Command-line Client: If you prefer not to use MCP clients, you can use the command-line client:

   # Interactive mode
   uv run python -m clients.mailbox_client
   
   # Command-line mode
   uv run python -m clients.mailbox_client list-emails --limit 10
   

Default behavior (cache, sync, version)

• list_emails defaults to cache (use_cache=true) with limit=100 and folder=all. Set use_cache=false to hit live IMAP, and adjust limit as needed.
• Local cache is de-duplicated via unique key (account_id, folder_id, uid) with upsert; cache queries also use DISTINCT to avoid repeats.
• Sync scheduler times are shown in local time; intervals support 5-minute cadence. Use sync_emails status / force to inspect or trigger sync.
• Service version comes from src/config/version.py and is exposed via the MCP get_version tool and the CLI “Version” menu.

Main Features

Note: The following commands are used within MCP clients (like Claude Desktop), not as command-line commands.

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

Command-line Mailbox Client

A standalone CLI lives under clients/mailbox_client, allowing you to browse emails across all configured accounts without launching an MCP client.

Interactive Mode (Recommended for beginners)

# Start interactive mode (like setup.py)
uv run python -m clients.mailbox_client

Interactive menu now covers: list/search emails, sync status/force sync, health, version, and DB maintenance (vacuum/clear cache). Listing defaults to cache with limit 100; pass --limit to expand or --use-cache false to hit live IMAP.

Command-line Mode (For scripting)

uv run python -m clients.mailbox_client list-accounts
uv run python -m clients.mailbox_client list-emails --limit 20
uv run python -m clients.mailbox_client show-email 123456 --account-id my_account

Each command accepts --json for machine-readable output. See clients/mailbox_client/README.md for more details.

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
4. Duplicates or stale cache: Cache uses unique key (account_id, folder_id, uid) with upsert; if DB is corrupted, remove data/email_sync.db and re-sync. Use sync_emails status to confirm scheduler (local time, 5-minute cadence supported).

AI Monitoring Issues

5. AI Filtering Failed: System automatically falls back to keyword filtering if AI API fails
6. Webhook Not Working: Verify webhook URL and test with python scripts/test_lark_webhook.py
7. n8n Workflow Errors: Check environment variables (FEISHU_WEBHOOK, OPENAI_API_KEY)
8. Script Permission Denied: Run chmod +x scripts/*.py to make scripts executable
9. 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
├── clients/                  # Standalone clients and tooling
│   └── mailbox_client/       # Command-line mailbox browser
└── 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

• docs/guides/EMAIL_TRANSLATE_WORKFLOW_GUIDE.md - Email translation & summarization workflow
• docs/guides/HTTP_API_QUICK_START.md - HTTP API quick start
• docs/guides/N8N_EMAIL_MONITORING_GUIDE.md - n8n email monitoring guide
• docs/guides/LARK_SETUP_GUIDE.md - Feishu/Lark webhook setup

Deployment & Security

• docs/guides/FINAL_DEPLOYMENT_CHECKLIST.md - Deployment checklist
• docs/guides/PRODUCTION_DEPLOYMENT_GUIDE.md - Production deployment guide
• docs/guides/SECURITY_SETUP_GUIDE.md - Security configuration

Technical Documentation

• docs/README.md - Complete documentation index
• docs/ARCHITECTURE.md - System architecture and design
• docs/database_design.md - Database schema and design
• n8n/README.md - n8n workflow details
• config_templates/ - Configuration templates and examples
• data/README.md - Data directory usage guide

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:

<div align="center"> <img src=".github/wechatpay.JPG" alt="WeChat Pay QR Code" width="300"/> <img src=".github/alipay.JPG" alt="Alipay QR Code" width="300"/> <p><i>Scan to support via WeChat Pay or Alipay</i></p> </div>

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

• [x] Multi-account email management
• [x] AI-powered email filtering
• [x] Email translation & summarization (OpenAI)
• [x] Multi-platform notifications
• [x] n8n workflow automation
• [x] 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.