Skip to main content
Glama
leeguooooo

MCP Email Service

by leeguooooo
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

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 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

  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 ├── 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

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:

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.

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/leeguooooo/email-mcp-service'

If you have feedback or need assistance with the MCP directory API, please join our Discord server