Email Send/Receive MCP Server

A Model Context Protocol (MCP) server for sending and receiving emails via SMTP, POP3, and IMAP. Built with FastMCP 2.0, this server enables AI assistants like Claude to interact with email services, making it easy to automate email workflows, check inboxes, and send messages programmatically.

🎯 What is MCP?

The Model Context Protocol (MCP) is an open standard that enables AI applications to securely connect to external data sources and tools. This server implements MCP to give AI assistants the ability to:

• Send emails with attachments, CC/BCC support

• Receive and read emails from IMAP/POP3 servers

• Search and filter email messages

• Work with multiple email providers (Gmail, Outlook, Yahoo, etc.)

Perfect for integration with AI assistants like Claude Desktop, this server acts as a bridge between conversational AI and your email infrastructure.

✨ Features

📤 Email Sending (SMTP)

• ✅ Send emails with validated recipient addresses

• ✅ Support for CC (Carbon Copy) and BCC (Blind Carbon Copy)

• ✅ HTML and plain text email bodies

• ✅ File attachments support with size validation

• ✅ Configurable sender information (name and email)

• ✅ Batch email validation for multiple recipients

• ✅ Smart TLS/SSL connection handling

📥 Email Receiving (IMAP/POP3)

• ✅ Retrieve emails from IMAP servers with full folder support

• ✅ POP3 protocol support for simple email retrieval

• ✅ Filter by mailbox/folder (INBOX, Sent, Drafts, etc.)

• ✅ Unread emails filtering

• ✅ Attachment information extraction

• ✅ Email metadata parsing (sender, subject, date, etc.)

• ✅ Body preview with length limiting

🔒 Email Validation & Security

• ✅ RFC-compliant email address validation

• ✅ Automatic email normalization

• ✅ Batch validation for multiple recipients

• ✅ App Password support for major providers

• ✅ TLS/SSL encryption for all connections

• ✅ Secure credential management via environment variables

📋 Table of Contents

• Quick Start

• Installation

• Configuration

• MCP Tools (Functions)

• Usage Examples

• Testing

• Integration with MCP Clients

• Docker Deployment

• Architecture

• Troubleshooting

• Contributing

🚀 Quick Start

Get started in 5 minutes! Follow these steps:

For detailed quick start instructions, see QUICKSTART.md.

📦 Installation

Prerequisites

• Python 3.11 or higher - Download Python

• Email account with SMTP/IMAP access (Gmail, Outlook, Yahoo, etc.)

• App Password for your email provider (for Gmail, Outlook, Yahoo)

Method 1: Using uv (Recommended)

uv is a fast Python package manager that simplifies dependency management.

Method 2: Using pip

Verify Installation

⚙️ Configuration

Step 1: Create Environment File

1. Copy the example environment file:

2. Edit .env with your email server credentials:

Step 2: Email Provider Setup

Gmail Setup (Most Common)

For Gmail, you'll need to:

1. Enable 2-Factor Authentication

   • Go to Google Account Security

   • Enable 2-Step Verification

2. Generate an App Password

   • Visit App Passwords

   • Select "Mail" and your device

   • Copy the generated 16-character password

   • Use this password in your .env file

3. Enable IMAP Access (for receiving emails)

   • Open Gmail → Settings → See all settings

   • Go to "Forwarding and POP/IMAP" tab

   • Enable IMAP

   • Save Changes

Gmail Configuration:

Other Email Providers

For configuration details for Outlook, Yahoo, ProtonMail, iCloud, and custom SMTP servers, see EMAIL_PROVIDERS.md.

Configuration Parameters Explained

Security Best Practices

⚠️ Important Security Notes:

1. Never commit with real credentials to version control

2. Always use App Passwords instead of your main account password

3. Enable 2-Factor Authentication on your email account

4. Use TLS/SSL for all email connections

5. Store secrets securely in production (Azure Key Vault, AWS Secrets Manager, etc.)

6. Rotate passwords regularly and revoke unused app passwords

7. Limit permissions to only what's necessary

🛠️ MCP Tools (Functions)

This server exposes 3 powerful MCP tools that AI assistants can use to interact with email services. Each tool is thoroughly documented below.

1. send_email - Send Emails via SMTP

Send emails with full support for attachments, CC/BCC, and HTML formatting.

Function Signature:

Parameters:

Returns:

• Success: Formatted confirmation message with delivery details

• Error: Error message explaining what went wrong

Example Usage in Claude:

Example Response:

Features:

• ✅ Automatic email address validation and normalization

• ✅ File attachment with size validation (default max: 25MB)

• ✅ Support for multiple CC and BCC recipients

• ✅ HTML email support with proper MIME encoding

• ✅ Smart SMTP connection handling (TLS/SSL)

• ✅ Detailed error messages for troubleshooting

2. receive_emails_imap - Retrieve Emails via IMAP

Retrieve and read emails from IMAP servers with advanced filtering options.

Function Signature:

Parameters:

Returns:

• Formatted list of emails with metadata and body previews

• Each email includes: ID, From, To, Subject, Date, Body Preview, Attachments

Example Usage in Claude:

Example Response:

Features:

• ✅ Support for all IMAP folders (INBOX, Sent, Drafts, custom folders)

• ✅ Unread-only filtering

• ✅ Attachment detection and metadata extraction

• ✅ Email body preview (first 200 characters)

• ✅ Full metadata parsing (sender, recipient, date, subject)

• ✅ Handles multiple encodings and international characters

• ✅ Secure SSL/TLS connection

Supported Mailbox Names:

• INBOX - Primary inbox

• Sent - Sent emails

• Drafts - Draft messages

• Trash - Deleted items

• Spam or Junk - Spam folder

• Custom folders created by the user

3. receive_emails_pop3 - Retrieve Emails via POP3

Retrieve emails using the simpler POP3 protocol (note: POP3 is less feature-rich than IMAP).

Function Signature:

Parameters:

Returns:

• Formatted list of emails (similar to IMAP output)

Example Usage in Claude:

Features:

• ✅ Simple email retrieval

• ✅ Attachment detection

• ✅ Email metadata parsing

• ✅ SSL/TLS support

Note: POP3 has limitations compared to IMAP:

• ❌ No folder support (only retrieves from main inbox)

• ❌ No unread filtering

• ❌ Less efficient for large mailboxes

• ✅ Use IMAP when possible for better features

Tool Comparison

💡 Usage Examples

Running the MCP Server

Start the server in HTTP mode (for MCP client connections):

The server will:

1. Load configuration from .env file

2. Initialize SMTP, IMAP, and POP3 services

3. Start listening on http://0.0.0.0:8888/mcp

4. Expose MCP tools for AI assistants to use

5. Log all activities to console and log files

Server Output:

Example 1: Send a Simple Text Email

Natural Language Request (via Claude):

What Happens:

• Claude uses the send_email tool

• Email address is validated

• Email is sent via configured SMTP server

• Confirmation is returned

MCP Tool Call (Behind the Scenes):

Response:

Example 2: Send HTML Email with Attachments

Natural Language Request:

MCP Tool Call:

Example 3: Send Email with CC and BCC

Natural Language Request:

MCP Tool Call:

Example 4: Check Unread Emails

Natural Language Request:

MCP Tool Call:

Response:

Example 5: Check Specific Email Folder

Natural Language Request:

MCP Tool Call:

Example 6: Retrieve Emails with Attachments

Natural Language Request:

MCP Tool Call:

Response (showing attachment info):

Example 7: Using POP3 for Simple Retrieval

Natural Language Request:

MCP Tool Call:

Programmatic Usage (Python)

If you want to use the email services directly in Python (without MCP):

For more examples, see examples.py in the repository.

🧪 Testing

This project includes comprehensive test coverage for validators, configuration, and core functionality.

Running Tests

Run All Tests

Run Specific Test Files

Test Coverage

The project includes tests for:

✅ Email Validation (tests/test_validators.py)

• Valid email address validation

• Invalid email detection (missing @, invalid domain, etc.)

• Email normalization

• Batch email validation

• Email formatting with names

✅ Configuration Management (tests/test_config.py)

• Settings loading from environment

• Default value validation

• Port number validation

• Field type validation

✅ SMTP Testing (test_smtp.py, test_smtp_variations.py)

• SMTP connection testing

• Email sending variations

• Different provider configurations

✅ Integration Tests (test_kakao_specific.py)

• Provider-specific testing

• Real-world scenarios

Example Test Output

Writing New Tests

When adding new features, include tests following this pattern:

Integration Testing

For testing with real email servers:

1. Create a test email account (don't use your primary account)

2. Set up test credentials in .env.test:

   SMTP_SERVER=smtp.gmail.com SMTP_PORT=587 SMTP_USERNAME=test-account@gmail.com SMTP_PASSWORD=test-app-password

3. Run integration tests (not included in default test suite):

   pytest tests/integration/ -v --env-file=.env.test

Manual Testing

You can test the MCP server manually:

1. Start the server:

   python main.py

2. Test with curl (health check):

   curl http://localhost:8888/api/health # Expected: {"status":"ok"}

3. Test email sending (using examples.py):

   python examples.py

Testing Checklist

Before submitting code:

• All existing tests pass (pytest tests/ -v)

• New tests added for new features

• Code coverage maintained or improved

• Tests follow naming conventions (test_*.py, Test* classes)

• Async tests use @pytest.mark.asyncio decorator

• Integration tests are marked separately

Continuous Integration

This project is ready for CI/CD integration. Example GitHub Actions workflow:

🔌 Integration with MCP Clients

This server is compatible with any MCP client. Below are detailed instructions for popular clients.

Claude Desktop Integration

Claude Desktop is Anthropic's official desktop app that supports MCP servers.

Setup Instructions

1. Locate Claude Desktop Configuration File

   The configuration file location varies by operating system:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add Email MCP Server to Configuration

   Option A: Using Environment Variables (Recommended)

   { "mcpServers": { "email": { "command": "python", "args": ["/absolute/path/to/email-send-mcp/main.py"], "env": { "SMTP_SERVER": "smtp.gmail.com", "SMTP_PORT": "587", "SMTP_USERNAME": "your-email@gmail.com", "SMTP_PASSWORD": "your-app-password", "IMAP_SERVER": "imap.gmail.com", "IMAP_PORT": "993", "IMAP_USERNAME": "your-email@gmail.com", "IMAP_PASSWORD": "your-app-password", "DEFAULT_FROM_EMAIL": "your-email@gmail.com" } } } }

   Option B: Using .env File (Simpler)

   { "mcpServers": { "email": { "command": "python", "args": ["/absolute/path/to/email-send-mcp/main.py"], "cwd": "/absolute/path/to/email-send-mcp" } } }

   This option assumes you have a .env file in the project directory.

3. Restart Claude Desktop

   After updating the configuration, fully quit and restart Claude Desktop.

4. Verify Integration

   In Claude Desktop, you should see email tools available. Try asking:

   Can you help me send an email?

   Claude should recognize it has access to the send_email tool.

Using Email Tools in Claude Desktop

Once configured, you can use natural language to interact with emails:

Sending Emails:

• "Send an email to john@example.com with subject 'Meeting' and tell him about tomorrow's meeting"

• "Email the team about the project update"

• "Send an email with the quarterly report attached"

Receiving Emails:

• "Check my inbox for unread emails"

• "Show me the last 10 emails I received"

• "What emails with attachments do I have?"

• "Check my Sent folder"

Other MCP Clients

This server works with any MCP-compatible client:

Custom MCP Client

HTTP MCP Client

The server also supports HTTP transport for web-based integrations:

Environment Variable Reference for MCP Clients

When configuring MCP clients, these environment variables are required:

Minimum Required Variables:

For Email Receiving (Optional):

Troubleshooting MCP Integration

Issue: Tools not appearing in Claude Desktop

• Solution: Verify the config file path is correct

• Solution: Check that the Python path is absolute

• Solution: Restart Claude Desktop after configuration changes

Issue: "Module not found" errors

• Solution: Ensure dependencies are installed (pip install -e .)

• Solution: Use the full Python path (e.g., /usr/local/bin/python3)

Issue: Authentication errors

• Solution: Verify environment variables are set correctly

• Solution: Check that app passwords are used (not regular passwords)

• Solution: Verify SMTP/IMAP credentials are correct

Issue: Server not starting

• Solution: Check logs in the logs/ directory

• Solution: Verify .env file exists and is readable

• Solution: Test server manually: python main.py

🐳 Docker Deployment

Docker provides a containerized way to run the Email MCP Server, ensuring consistency across different environments.

Prerequisites

• Docker installed (Get Docker)

• Docker Compose (optional, for multi-container setups)

Quick Start with Docker

Step 1: Build the Docker Image

This creates a Docker image with all dependencies installed.

Step 2: Run the Container

Option A: Using Environment Variables

Option B: Using .env File (Recommended)

Step 3: Verify Container is Running

Docker Compose Setup

For easier management, use Docker Compose:

docker-compose.yml

Start with Docker Compose:

Docker Management Commands

Production Docker Best Practices

1. Use Multi-Stage Builds (already in Dockerfile)

2. Run as Non-Root User (already configured)

3. Use Health Checks (see Docker Compose example)

4. Mount Logs as Volumes for persistence

5. Use Secrets Management for production credentials

6. Set Resource Limits:

☁️ Azure Container Apps Deployment

Deploy the Email MCP Server to Azure Container Apps for scalable, serverless hosting.

Prerequisites

• Azure account with active subscription

• Azure CLI installed (Install Azure CLI)

• Docker installed

Deployment Steps

Step 1: Login to Azure

Step 2: Create Resource Group

Step 3: Create Azure Container Registry (ACR)

Step 4: Build and Push Image to ACR

Step 5: Create Container Apps Environment

Step 6: Deploy Container App

Step 7: Get Application URL

Azure Container Apps Features

✅ Auto-scaling: Automatically scales based on HTTP traffic ✅ Zero Downtime: Seamless deployments with rolling updates ✅ Built-in Load Balancing: Distributes traffic across replicas ✅ HTTPS by Default: Automatic SSL/TLS certificates ✅ Secrets Management: Secure credential storage ✅ Monitoring: Integrated with Azure Monitor and Application Insights

Update Deployment

Monitoring and Logs

Cost Optimization

• Use consumption plan (pay only for what you use)

• Set appropriate min/max replicas

• Configure scale rules based on metrics

• Use reserved capacity for predictable workloads

Security Best Practices

1. Use Azure Key Vault for secrets

2. Enable Managed Identity for ACR authentication

3. Use Private Endpoints for internal-only access

4. Configure CORS policies

5. Enable Azure AD authentication for API access

6. Use VNet integration for enhanced security

🏗️ Architecture

System Architecture

Project Structure

Component Details

1. main.py - Application Entry Point

• Loads environment variables from .env

• Configures logging (console + file)

• Initializes FastMCP server

• Sets up SMTP, IMAP, POP3 services

• Starts HTTP server on port 8888

2. src/config.py - Configuration Management

• Uses Pydantic Settings for type-safe configuration

• Loads settings from environment variables

• Validates port numbers and required fields

• Provides singleton pattern for settings access

• Supports multiple email providers

3. src/server.py - MCP Server

• Defines MCP tools using @mcp.tool() decorator

• Integrates EmailSender and EmailReceiver services

• Handles tool parameter validation

• Formats responses for AI assistants

• Provides health check endpoint

4. src/services/email_sender.py - SMTP Service

• Async SMTP client using aiosmtplib

• Supports TLS (port 587) and SSL (port 465)

• Validates all email addresses before sending

• Handles file attachments with size limits

• Supports CC, BCC, and HTML emails

• Smart MIME message construction

5. src/services/email_receiver.py - IMAP/POP3 Service

• Async IMAP client using aioimaplib

• Sync POP3 client using poplib

• Folder/mailbox support (IMAP)

• Unread filtering (IMAP)

• Email parsing with proper encoding handling

• Attachment metadata extraction

6. src/utils/validators.py - Email Utilities

• RFC-compliant email validation using email-validator

• Email normalization and formatting

• Batch email validation

• Display name formatting

Technology Stack

Data Flow

Sending an Email

Receiving Emails

Logging and Monitoring

• Log Location: logs/email-send-mcp_YYYYMMDD.log

• Log Rotation: Daily (midnight)

• Log Format: YYYY-MM-DD HH:MM:SS - logger_name - LEVEL - message

• Log Levels: DEBUG, INFO, WARNING, ERROR

• Console Output: Enabled for development

• Structured Logging: JSON-compatible format for cloud environments

Security Architecture

1. Credential Storage: Environment variables (never hardcoded)

2. TLS/SSL: Enforced for all email connections

3. Input Validation: All emails validated before processing

4. Attachment Validation: File size and existence checks

5. Error Handling: Sensitive data not exposed in errors

6. Logging: Passwords and secrets never logged

🔧 Troubleshooting

Common Issues and Solutions

Issue: "Authentication failed" or "Invalid credentials"

Symptoms:

• Error message: "535 Authentication failed" or similar

• Cannot connect to SMTP/IMAP server

Solutions:

1. Use App Password instead of regular password

   • For Gmail: Create App Password

   • For Yahoo: Account Security → Generate app password

   • For Outlook: May need app-specific password or OAuth

2. Verify credentials in

   # Check your .env file cat .env | grep -E "USERNAME|PASSWORD"

3. Ensure 2FA is enabled (required for app passwords)

4. Check IMAP/SMTP access is enabled

   • Gmail: Settings → See all settings → Forwarding and POP/IMAP → Enable IMAP

   • Outlook: Settings → Sync email → POP and IMAP

Issue: "Connection timeout" or "Connection refused"

Symptoms:

• Server doesn't respond

• Timeout errors after 60+ seconds

Solutions:

1. Check firewall settings

   # Test SMTP connectivity telnet smtp.gmail.com 587 # Test IMAP connectivity telnet imap.gmail.com 993

2. Verify server addresses and ports

   • SMTP: Usually port 587 (TLS) or 465 (SSL)

   • IMAP: Usually port 993 (SSL)

   • POP3: Usually port 995 (SSL)

3. Check if your ISP blocks SMTP/IMAP ports

   • Some ISPs block port 25, 587

   • Try using VPN or alternative network

4. Verify TLS/SSL settings match your provider

   # For port 587, use: SMTP_USE_TLS=true # For port 465, use: SMTP_USE_TLS=true # aiosmtplib handles this automatically

Issue: Gmail "Less secure app access" error

Symptoms:

• "Please log in via your web browser" error

• Account access blocked

Solutions:

1. Enable 2-Factor Authentication

   • Go to Google Account Security

   • Turn on 2-Step Verification

2. Generate and use App Password

   • Visit App Passwords

   • Select "Mail" and your device

   • Copy the 16-character password

   • Use in .env file (remove spaces)

3. Never use "Less secure app access" (deprecated and insecure)

Issue: "Module not found" errors

Symptoms:

Solutions:

Issue: "Permission denied" or "File not found" (attachments)

Symptoms:

• "Attachment file not found: /path/to/file.pdf"

• Permission errors when reading attachment files

Solutions:

1. Use absolute paths for attachments

   # ✅ Good attachments=["/home/user/documents/report.pdf"] # ❌ Bad attachments=["report.pdf"]

2. Verify file exists and is readable

   ls -la /path/to/file.pdf # Should show readable permissions

3. Check file size

   # Default max is 25MB du -h /path/to/file.pdf

Issue: "Tools not appearing in Claude Desktop"

Symptoms:

• MCP server configured but tools don't show up

• Claude doesn't recognize email commands

Solutions:

1. Verify config file path is correct

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Use absolute paths in configuration

   { "mcpServers": { "email": { "command": "python", "args": ["/absolute/path/to/email-send-mcp/main.py"] } } }

3. Restart Claude Desktop completely

   • Quit application (not just close window)

   • Restart from Applications/Start Menu

4. Check server logs

   # View logs to see if server started tail -f logs/email-send-mcp_*.log

Issue: Email sends but recipient doesn't receive it

Symptoms:

• "Email sent successfully" message

• But recipient never receives the email

Solutions:

1. Check recipient's spam/junk folder

2. Verify sender email is correct

   DEFAULT_FROM_EMAIL=your-actual-email@gmail.com

3. Check email provider's sent folder

4. Verify recipient email address is valid

   # Test email validation from src.utils.validators import validate_email_address is_valid, result = validate_email_address("recipient@example.com") print(f"Valid: {is_valid}, Result: {result}")

5. Check for bounce-back emails in your inbox

Issue: "Maximum attachment size exceeded"

Symptoms:

• Error about attachment size limit

Solutions:

1. Check file size

   du -h attachment.pdf

2. Increase limit in

   MAX_ATTACHMENT_SIZE_MB=50 # Default is 25

3. Compress large files before attaching

4. Use cloud storage links for very large files

Issue: Cannot receive emails / Empty inbox

Symptoms:

• "No emails found" message

• IMAP returns empty results

Solutions:

1. Verify IMAP credentials are correct

   IMAP_USERNAME=your-email@gmail.com IMAP_PASSWORD=your-app-password

2. Check mailbox name is correct

   # Common mailbox names receive_emails_imap(mailbox="INBOX") # ✅ receive_emails_imap(mailbox="Sent") # ✅ receive_emails_imap(mailbox="inbox") # ❌ Case-sensitive

3. Verify emails exist in that folder

   • Check via web interface

   • Try different folder: "Sent", "Drafts", etc.

4. Increase limit parameter

   receive_emails_imap(limit=50) # Default is 10

Debugging Tips

Enable Debug Logging

Add to .env:

Restart server and check logs:

Test SMTP Connection Manually

Test IMAP Connection Manually

Check Environment Variables

Getting Help

If you're still experiencing issues:

1. Check existing issues: GitHub Issues

2. Search discussions: GitHub Discussions

3. Open a new issue:

   • Include error messages

   • Include relevant logs (remove sensitive data)

   • Include your configuration (without passwords)

   • Include steps to reproduce

👥 Contributing

We welcome contributions! Here's how you can help:

Quick Start for Contributors

1. Fork and clone the repository

   git clone https://github.com/YOUR_USERNAME/email-send-mcp.git cd email-send-mcp

2. Install development dependencies

   pip install -e ".[dev]"

3. Create a branch

   git checkout -b feature/your-feature-name

4. Make your changes and add tests

5. Run tests and linting

   # Run tests pytest tests/ -v # Format code black src/ tests/ main.py isort src/ tests/ main.py # Type checking mypy src/ # Linting ruff check src/ tests/

6. Commit and push

   git commit -m "Add feature: description" git push origin feature/your-feature-name

7. Create Pull Request

Contribution Guidelines

• Code Style: Follow PEP 8, use Black formatter

• Tests: Add tests for new features

• Documentation: Update README and docstrings

• Commits: Write clear commit messages

• Issues: Link PRs to related issues

For detailed guidelines, see CONTRIBUTING.md.

📚 Additional Resources

• QUICKSTART.md - Get started in 5 minutes

• EMAIL_PROVIDERS.md - Provider-specific configurations

• CONTRIBUTING.md - Contribution guidelines

• examples.py - Code examples

• FastMCP Documentation - MCP framework docs

• Model Context Protocol - MCP specification

📄 License

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

🙏 Acknowledgments

• FastMCP - Excellent MCP framework by @jlowin

• Anthropic - Model Context Protocol specification

• Contributors - Thank you to all contributors!

📞 Support

• Issues: GitHub Issues

• Discussions: GitHub Discussions

• Email: For private inquiries only

⭐ Star this repo if you find it useful!

Made with ❤️ for the MCP community