Docs & Usage Guide

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 [email protected] saying the meeting is tomorrow at 2 PM"

Send with HTML formatting:

"Send an HTML email to [email protected] 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 [email protected], CC [email protected], and attach the project report"

Email Provider Setup

For Gmail

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

Gmail Setup Steps:

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

For Outlook

"env": {
    "SMTP_HOST": "smtp-mail.outlook.com",
    "SMTP_PORT": "587",
    "SMTP_SECURE": "false",
    "SMTP_USER": "[email protected]",
    "SMTP_FROM": "[email protected]",
    "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	`[email protected]`
`SMTP_FROM`	Sender address	`[email protected]`
`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.

Email SMTP