Emails MCP Server

A FastMCP-based email management server for IMAP/SMTP operations through the Model Context Protocol (MCP).

Features

• 📧 Email Management: Get, read, search emails with pagination support
• 📤 Send & Reply: Send emails with HTML/text, attachments, CC/BCC support
• 📁 Folder Operations: List, create, delete email folders
• 📋 Draft Management: Save, update, delete, and manage email drafts
• 📦 Import/Export: Backup/restore emails with folder structure preservation
• 🔗 Attachment Handling: Download email attachments to specified locations
• 📊 Statistics: Get mailbox statistics and unread counts
• 🛡️ Security: Workspace isolation and secure IMAP/SMTP connections

Installation

Uv is recommanded

uv tool install emails-mcp

From source

git clone https://github.com/lockon-n/emails-mcp.git
cd emails-mcp
uv sync

Usage

Configuration

Create email configuration file (/path/to/your/email/config.json):

Single account format:

{
    "email": "your-email@example.com",
    "password": "your-password", 
    "name": "Your Name",
    "imap_server": "imap.example.com",
    "imap_port": yourport (typically 993),
    "smtp_server": "smtp.example.com",
    "smtp_port": yourport (typically 587),
    "use_ssl": true/false,
    "use_starttls": true/false
}

Usage with Claude Desktop

Add to your ~/.config/claude/claude_desktop_config.json (Linux/macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

Published Configuration:

{
  "mcpServers": {
    "emails-mcp": {
      "command": "uvx",
      "args": [
        "emails-mcp",
        "--config_file",
        "</path/to/your/email/config.json>",
        "--attachment_upload_path",
        "<your/upload/directory>",
        "--attachment_download_path",
        "<your/downloads/directory>",
        "--email_export_path",
        "<your/exports/directory>"
      ]
    }
  }
}

Development/Unpublished Configuration:

{
  "mcpServers": {
    "emails-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "<path/to/emails-mcp>",
        "run",
        "emails-mcp",
        "--config_file", 
        "</path/to/your/email/config.json>",
        "--attachment_upload_path",
        "<your/upload/directory>",
        "--attachment_download_path",
        "<path/to/your/config.json>",
        "--email_export_path",
        "<your/exports/directory>"
      ]
    }
  }
}

Note: For security, this tool restricts file operations to the specified directories:

• --attachment_upload_path: Restricts attachment file selection
• --attachment_download_path: Where downloaded attachments are saved
• --email_export_path: Where email exports are saved

As a command line tool

# Basic usage (uses default config file: test_emils.json)
emails-mcp

# With custom configuration file
emails-mcp --config_file config.json

# With path restrictions for security
emails-mcp --config_file config.json \
  --attachment_download_path ./downloads \
  --email_export_path ./exports \
  --attachment_upload_path ./uploads

# With debug logging
emails-mcp --config_file config.json --debug

Supported Arguments

• --config_file: Email configuration file path
• --attachment_upload_path: Directory for attachment uploads (restricts file selection)
• --attachment_download_path: Directory for attachment downloads (files saved here)
• --email_export_path: Directory for email exports (exports saved here)
• --debug: Enable debug logging

Available Tools

Configuration Options

Email Server Settings

• IMAP/SMTP servers: Configure your email provider's servers
• Security: Supports SSL/TLS and STARTTLS
• Authentication: Standard username/password authentication

Workspace Security

• Path Restriction: Limit file operations to specified directory
• Path Validation: All file paths are validated for security

Pagination

• Default page size: 20 items per page
• Maximum page size: 50 items per page
• Auto-correction: Invalid page parameters are automatically corrected

Error Handling

The server includes comprehensive error handling:

• Connection errors: Graceful handling of network issues
• Authentication errors: Clear error messages for login failures
• Validation errors: Input validation with helpful error messages
• File system errors: Proper handling of file operation failures

Security Considerations

• Workspace isolation: File operations can be restricted to a safe directory
• Input validation: All user inputs are validated
• Connection security: Supports SSL/TLS encryption
• Error messages: Avoid exposing sensitive information in error messages

Development

Build

uv build

Publish to PyPI

uv publish

Local Development

# Install development dependencies
uv sync

# Run tests
uv run python -m pytest

# Run server
uv run python -m emails_mcp.server

Project Structure

The codebase follows software engineering best practices:

- models/          # Data models and configurations
- config/          # Configuration management  
- utils/           # Utilities, validators, and parsers
- backends/        # IMAP, SMTP, and file operation backends
- services/        # Business logic layer
- tools/           # MCP tool definitions
- server.py        # Main MCP server entry point

License

MIT License

Contributing

Issues and Pull Requests are welcome!