Email MCP Server

What is Email MCP Server about?

Email MCP Server provides a lightweight MCP endpoint that lets AI assistants issue email‑sending commands. It abstracts the SMTP interaction so the model only needs to specify recipients, subject, body, and optional attachments.

How to use Email MCP Server?

1. Install uv (Python package manager) and sync dependencies:

   curl -LsSf https://astral.sh/uv/install.sh | sh
   source ~/.bashrc
   cd email-mcp-server
   uv sync
   

2. Configure SMTP environment variables (e.g., Gmail, Outlook) in the MCP server configuration used by Claude Desktop or Cursor.
3. Run the server for testing or production:

   uv run main.py
   

4. Invoke tools (send_email, send_custom_email, test_smtp_connection_tool) from your AI agent to perform email actions.

Key Features of Email MCP Server

• Simple send_email tool for quick plain‑text messages.
• Advanced send_custom_email tool with HTML support, multiple recipients, CC/BCC, and file attachments.
• test_smtp_connection_tool to verify SMTP credentials before sending real emails.
• Environment‑driven configuration (host, port, TLS/SSL, user, password, sender address).
• Works with any SMTP provider (Gmail, Outlook, custom servers).

Use Cases of Email MCP Server

• Automated report distribution from AI‑driven analytics pipelines.
• Notification emails triggered by workflow events (e.g., build failures, data updates).
• Customer support agents that draft and send personalized emails.
• Scheduled newsletters generated by language models.

FAQ from the Email MCP Server

Q: Which email providers are supported? A: Any provider offering SMTP access. Configuration examples for Gmail and Outlook are provided.

Q: Do I need to store my password in plain text? A: Use environment variables or secret management tools. For Gmail, generate an app‑specific password.

Q: How do I test the connection without sending an email? A: Run test_smtp_connection_tool or execute uv run python test_email.py which only attempts a login.

Q: Can I override SMTP settings per email? A: Yes, send_custom_email accepts optional parameters to change host, port, or credentials for a single message.

Q: What if my network blocks SMTP ports? A: Verify that ports 587 (STARTTLS) or 465 (SSL) are open, or use a VPN/relay service.

Email MCP Server

This MCP (Model Context Protocol) server lets your AI assistant send emails for you.

What Can It Do?

Your AI assistant can:

• Send both plain text and HTML emails
• Attach files and documents
• Send to multiple people with CC/BCC
• Check if your email setup works

Available Tools

send_email - Simple Email Sending

Send emails quickly using your environment configuration:

• Just specify recipient, subject, and body
• Automatically uses your configured SMTP settings
• Perfect for quick messages

send_custom_email - Advanced Email Features

Send emails with full control:

• Send to multiple people with CC/BCC
• Add file attachments
• Use HTML formatting
• Override SMTP settings per email

test_smtp_connection_tool - Check Setup

Test your email settings before sending important emails.

Getting Started

1. Install Required Software

# Install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Restart your terminal or run:
source ~/.bashrc

2. Install Project Dependencies

cd email-mcp-server
uv sync

3. Test the Installation

# Test your email setup
uv run python test_email.py

# Run the server directly (for testing)
uv run main.py

4. Configure Claude Desktop or Cursor

Add this to your Claude Desktop configuration or Cursor file:

{
  "mcpServers": {
      "mcp-server": {
          "command": "uv",
          "args": [
              "--directory",
              "path/to/the/app/email-mcp-server",
              "run",
              "main.py"
          ],
          "env": {
              "SMTP_HOST": "",
              "SMTP_PORT": "",
              "SMTP_SECURE": "",
              "SMTP_USER": "",
              "SMTP_FROM": "",
              "SMTP_PASS": ""
          }
      }
  }
}

Important: Change the directory path to match your actual installation location.

Simple Examples

Send a basic email:

"Send an email to john@company.com saying the meeting is tomorrow at 2 PM"

Send with HTML formatting:

"Send an HTML email to team@company.com with subject 'Weekly Update' and create a nice formatted message about this week's progress"

Test your setup:

"Test the email connection to make sure it's working"

Advanced Examples

Send to multiple people with attachments:

"Send a custom email to the team about the project update. Send to team@company.com, CC manager@company.com, and attach the project report"

Email Provider Setup

For Gmail

"env": {
    "SMTP_HOST": "smtp.gmail.com",
    "SMTP_PORT": "587",
    "SMTP_SECURE": "false",
    "SMTP_USER": "your-email@gmail.com",
    "SMTP_FROM": "your-email@gmail.com",
    "SMTP_PASS": "your-app-password"
}

Gmail Setup Steps:

1. Enable 2-Factor Authentication
2. Go to Google Account → Security → App passwords
3. Generate an app password for "Mail"
4. Use the 16-character app password

For Outlook

"env": {
    "SMTP_HOST": "smtp-mail.outlook.com",
    "SMTP_PORT": "587",
    "SMTP_SECURE": "false",
    "SMTP_USER": "your-email@outlook.com",
    "SMTP_FROM": "your-email@outlook.com",
    "SMTP_PASS": "your-password"
}

For Other Providers

Replace the SMTP settings with your provider's details. Most providers use:

• Port 587 with SMTP_SECURE=false (STARTTLS)
• Port 465 with SMTP_SECURE=true (SSL)

Configuration Variables

Variable	Description	Example
SMTP_HOST	Your email server	smtp.gmail.com
SMTP_PORT	Server port	587
SMTP_SECURE	Use SSL (true/false)	false
SMTP_USER	Your username	user@gmail.com
SMTP_FROM	Sender address	noreply@company.com
SMTP_PASS	Your password	your-password

Troubleshooting

"Missing Configuration"

• Make sure all environment variables are set in the Claude Desktop config
• Check that the directory path is correct and absolute
• Restart Claude Desktop after making changes

"Authentication Failed"

• For Gmail/Yahoo: Use app passwords, not regular passwords
• Enable 2-Factor Authentication first
• Double-check username and password

"Connection Issues"

• Verify SMTP host and port are correct
• Check your internet connection
• Some networks block SMTP ports

"Server Not Found"

• Make sure uv is installed and in your PATH
• Check that the directory path exists
• Verify the project dependencies are installed with uv sync

Testing

# Test configuration and connection
uv run python test_email.py

# Send a real test email to yourself
uv run python test_email.py --send-real

License

MIT License - Feel free to use and modify as needed.