@souluanf/mcp-smtp

v0.1.2

Published

3 months ago

Generic SMTP Email MCP Server — send emails from any MCP-compatible app using any SMTP provider. Zero installation via npx.

0High
0Medium
0Low

souluanf

mcp smtp email nodemailer icloud gmail outlook sendgrid mailgun claude modelcontextprotocol typescript

mcp-smtp

Generic SMTP Email MCP Server — Send emails from Claude using any SMTP provider. Zero installation, plug-and-play via npx.

Supports iCloud, Gmail, Outlook, Yahoo, Zoho, Fastmail, Hostinger, SendGrid, Mailgun, Amazon SES, Postmark, Brevo, Resend, and many more.

Quick Start

No installation needed. Just add to your Claude Desktop (or any MCP client) configuration:

{
  "mcpServers": {
    "smtp-email": {
      "command": "npx",
      "args": ["-y", "@souluanf/mcp-smtp@latest"],
      "env": {
        "SMTP_HOST": "smtp.gmail.com",
        "SMTP_PORT": "587",
        "SMTP_SECURITY": "STARTTLS",
        "SMTP_USER": "[email protected]",
        "SMTP_PASSWORD": "xxxx-xxxx-xxxx-xxxx",
        "SMTP_FROM_NAME": "Your Name"
      }
    }
  }
}

Features

✅ Plain-text, HTML and mixed emails
✅ File attachments (multiple files)
✅ CC, BCC, Reply-To
✅ Auto-save to Sent folder via IMAP (fire-and-forget)
✅ Sender display name (SMTP_FROM_NAME)
✅ STARTTLS, SSL/TLS and plain (no encryption)
✅ Works with App Passwords (iCloud, Gmail, Outlook, Yahoo)
✅ IPv6-first DNS resolution — works even when ISPs block IPv4 to SMTP servers
✅ SNI support for TLS when connecting via raw IP
✅ Auto-detected IMAP Sent folder per provider
✅ Connection test tool
✅ Zero config — everything via environment variables

Client Setup

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "smtp-email": {
      "command": "npx",
      "args": ["-y", "@souluanf/mcp-smtp@latest"],
      "env": {
        "SMTP_HOST": "smtp.mail.me.com",
        "SMTP_PORT": "587",
        "SMTP_SECURITY": "STARTTLS",
        "SMTP_USER": "[email protected]",
        "SMTP_PASSWORD": "xxxx-xxxx-xxxx-xxxx",
        "SMTP_FROM_NAME": "Your Name",
        "IMAP_SENT_FOLDER": "Sent Messages"
      }
    }
  }
}

claude mcp add smtp-email \
  -e SMTP_HOST=smtp.gmail.com \
  -e SMTP_PORT=587 \
  -e SMTP_SECURITY=STARTTLS \
  -e [email protected] \
  -e SMTP_PASSWORD=xxxx-xxxx-xxxx-xxxx \
  -e SMTP_FROM_NAME="Your Name" \
  -- npx -y @souluanf/mcp-smtp@latest

Add to your MCP settings (.cursor/mcp.json, .windsurf/mcp.json, or equivalent):

{
  "mcpServers": {
    "smtp-email": {
      "command": "npx",
      "args": ["-y", "@souluanf/mcp-smtp@latest"],
      "env": {
        "SMTP_HOST": "smtp.gmail.com",
        "SMTP_PORT": "587",
        "SMTP_SECURITY": "STARTTLS",
        "SMTP_USER": "[email protected]",
        "SMTP_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}

Configuration

| Variable | Description | Required | Default | |--------------------|------------------------------------------|----------|--------------------------------| | SMTP_HOST | SMTP server hostname | ✅ | — | | SMTP_USER | Your email address (login) | ✅ | — | | SMTP_PASSWORD | Password or App Password | ✅ | — | | SMTP_PORT | SMTP port | — | 587 | | SMTP_SECURITY | STARTTLS | SSL | NONE | — | STARTTLS | | SMTP_FROM | Sender address | — | same as SMTP_USER | | SMTP_FROM_NAME | Sender display name | — | — | | SMTP_TIMEOUT | Connection timeout (seconds) | — | 30 | | SMTP_VERIFY_SSL | Verify SSL certificate | — | true | | IMAP_HOST | IMAP hostname for Sent folder | — | derived from SMTP_HOST | | IMAP_PORT | IMAP port | — | 993 | | IMAP_SENT_FOLDER | Sent folder name | — | auto-detected per provider |

SMTP_VERIFY_SSL=false is useful for self-signed certificates (e.g. ProtonMail Bridge).

Provider Reference

Personal Email

| Provider | SMTP_HOST | SMTP_PORT | SMTP_SECURITY | Notes | |-----------------------|--------------------------|-------------|-----------------|--------------------------| | iCloud | smtp.mail.me.com | 587 | STARTTLS | Use App Password | | Gmail | smtp.gmail.com | 587 | STARTTLS | Use App Password | | Outlook / 365 | smtp.office365.com | 587 | STARTTLS | Use App Password | | Yahoo Mail | smtp.mail.yahoo.com | 587 | STARTTLS | Use App Password | | AOL Mail | smtp.aol.com | 587 | STARTTLS | Use App Password | | Zoho Mail | smtp.zoho.com | 587 | STARTTLS | Use App Password | | Fastmail | smtp.fastmail.com | 587 | STARTTLS | Use App Password | | ProtonMail Bridge | 127.0.0.1 | 1025 | NONE | Requires Bridge desktop app; set SMTP_VERIFY_SSL=false | | GMX | mail.gmx.com | 587 | STARTTLS | Account password | | Mail.com | smtp.mail.com | 587 | STARTTLS | Account password |

Hosting Providers

| Provider | SMTP_HOST | SMTP_PORT | SMTP_SECURITY | Notes | |-----------------------|------------------------------------|-------------|-----------------|-------------------| | Hostinger | smtp.hostinger.com | 465 | SSL | Account password | | GoDaddy | smtpout.secureserver.net | 465 | SSL | Account password | | Namecheap / Private Email | mail.privateemail.com | 465 | SSL | Account password | | Bluehost | mail.bluehost.com | 465 | SSL | Account password | | SiteGround | smtp.siteground.com | 465 | SSL | Account password | | DreamHost | smtp.dreamhost.com | 465 | SSL | Account password | | cPanel (generic) | mail.yourdomain.com | 465 | SSL | Account password |

Transactional Providers

| Provider | SMTP_HOST | SMTP_PORT | SMTP_USER | SMTP_PASSWORD | |-----------------------|------------------------------------------|-------------|-------------------|-------------------| | SendGrid | smtp.sendgrid.net | 587 | apikey | Your API key | | Mailgun | smtp.mailgun.org | 587 | SMTP login | SMTP password | | Amazon SES | email-smtp.<region>.amazonaws.com | 587 | SMTP user | SMTP password | | Postmark | smtp.postmarkapp.com | 587 | API token | API token | | Brevo (Sendinblue)| smtp-relay.brevo.com | 587 | Your email | SMTP key | | Resend | smtp.resend.com | 465 | resend | Your API key | | SparkPost | smtp.sparkpostmail.com | 587 | SMTP_Injection | API key | | Mandrill (Mailchimp)| smtp.mandrillapp.com | 587 | Your email | API key | | Elastic Email | smtp.elasticemail.com | 2525 | Your email | API key |

Transactional providers require a verified sender domain. Use SMTP_SECURITY=STARTTLS unless noted otherwise.

Available Tools

| Tool | Description | |------------------------------|----------------------------------------------------------| | test_connection | Test your SMTP configuration before sending | | send_email | Send a plain-text email | | send_email_html | Send an email with HTML body (and optional plain-text fallback) | | send_email_with_attachment | Send an email with one or more file attachments |

Tool Parameters

| Parameter | Type | Required | Description | |----------------|------------|----------|------------------------------------------| | to | string[] | ✅ | Recipient email addresses | | subject | string | ✅ | Email subject | | body | string | ✅ | Plain-text body | | html_body | string | — | HTML body (send_email_html only) | | attachments | string[] | — | Absolute file paths (send_email_with_attachment) | | cc | string[] | — | CC recipients | | bcc | string[] | — | BCC recipients | | reply_to | string | — | Reply-To address |

Usage Examples

Send a plain email:

"Send an email to [email protected] with subject 'Hello' and body 'How are you?'"

Send an HTML email:

"Send an HTML email to [email protected] with a formatted table of this week's metrics."

Send with attachment:

"Email the file /Users/me/report.pdf to [email protected] with subject 'Monthly Report'."

Test connection:

"Test my SMTP connection."

App Password Setup

Most providers require an App Password when 2FA is enabled:

| Provider | Where to generate | |--------------|-----------------------------------------------------------------------------------| | iCloud | appleid.apple.com → Sign-In and Security → App-Specific Passwords | | Gmail | myaccount.google.com → Security → 2-Step Verification → App Passwords | | Outlook | Account settings → Security → Advanced security → App passwords | | Yahoo | Account Security → Generate app password | | Fastmail | Settings → Privacy & Security → Passwords → New App Password | | Zoho | My Account → Security → App Passwords |

Troubleshooting

Connection refused / ECONNREFUSED

Verify SMTP_HOST and SMTP_PORT match your provider's settings.
Some ISPs block port 587 on certain networks. Try switching to mobile data or a VPN to confirm.
For SSL providers, make sure SMTP_SECURITY=SSL and port is 465.

Authentication failed

Ensure you're using an App Password, not your account password, when 2FA is enabled.
For Gmail, ensure "Less secure app access" is off and you're using an App Password instead.

Sent emails not appearing in Sent folder

Set IMAP_SENT_FOLDER explicitly (see provider reference above).
iCloud requires IMAP_SENT_FOLDER=Sent Messages.
Gmail requires IMAP_SENT_FOLDER=[Gmail]/Sent Mail.

SSL certificate errors

Set SMTP_VERIFY_SSL=false for self-signed certificates (ProtonMail Bridge, local mail servers).

License

MIT — made with ☕ by Luan Fernandes