Enables sending emails via Gmail's SMTP server, allowing for message validation, attachment handling, and secure authentication.

1. Click on "Install Server".

2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.

3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mail-smtp-mcp Email jane@example.com about the project status update"

That's it! The server will respond to your query, and you can continue using it as needed.

Here is a step-by-step guide with screenshots.

npx -y @bradsjm/mail-smtp-mcp

pnpm install
pnpm dev

pnpm build

MAIL_SMTP_<ACCOUNT_ID>_<SETTING>=value

MAIL_SMTP_DEFAULT_HOST=smtp.gmail.com
MAIL_SMTP_DEFAULT_PORT=587
MAIL_SMTP_DEFAULT_SECURE=false
MAIL_SMTP_DEFAULT_USER=you@gmail.com
MAIL_SMTP_DEFAULT_PASS=your-app-password
MAIL_SMTP_DEFAULT_FROM=you@gmail.com

# Default account
MAIL_SMTP_DEFAULT_HOST=smtp.gmail.com
MAIL_SMTP_DEFAULT_USER=you@gmail.com
MAIL_SMTP_DEFAULT_PASS=app-password-1

# Work account
MAIL_SMTP_WORK_HOST=smtp.company.com
MAIL_SMTP_WORK_PORT=465
MAIL_SMTP_WORK_SECURE=true
MAIL_SMTP_WORK_USER=you@company.com
MAIL_SMTP_WORK_PASS=company-password
MAIL_SMTP_WORK_FROM=you@company.com

MAIL_SMTP_SEND_ENABLED=true

MAIL_SMTP_ALLOWLIST_DOMAINS=example.com,example.org
MAIL_SMTP_ALLOWLIST_ADDRESSES=alice@example.com,bob@example.org

{
 "account_id": "default" // Optional - filter by specific account
}

{
 "summary": "Found 2 configured SMTP account(s).",
 "data": {
 "accounts": [
 {
 "account_id": "default",
 "host": "smtp.gmail.com",
 "port": 587,
 "secure": false,
 "default_from": "you@gmail.com"
 },
 {
 "account_id": "work",
 "host": "smtp.company.com",
 "port": 465,
 "secure": true
 }
 ]
 },
 "_meta": {
 "send_enabled": true,
 "limits": {
 "max_recipients": 10,
 "max_message_bytes": 2500000,
 "max_attachments": 5,
 "max_attachment_bytes": 2000000
 }
 }
}

{
 "account_id": "default" // Defaults to "default"
}

┌─────────────────┐
│ Load Account │
│ Config │
└────────┬────────┘
 │
 ▼
┌─────────────────┐
│ Create SMTP │
│ Transport │
└────────┬────────┘
 │
 ▼
┌─────────────────┐
│ Verify Connect │
│ & Authenticate │
└────────┬────────┘
 │
 ▼
┌─────────────────┐
│ Return Status │
│ (ok / error) │
└─────────────────┘

{
 "summary": "SMTP account default verified successfully.",
 "data": {
 "account_id": "default",
 "status": "ok"
 }
}

{
 "account_id": "default", // Defaults to "default"
 "from": "sender@example.com", // Optional - override account default
 "to": ["recipient@example.com"], // Required - string or array
 "cc": ["cc@example.com"], // Optional
 "bcc": ["bcc@example.com"], // Optional
 "reply_to": "reply@example.com", // Optional
 "subject": "Test Email", // Required
 "text_body": "Plain text here", // Optional
 "html_body": "<p>HTML here</p>", // Optional
 "attachments": [ // Optional
 {
 "filename": "document.pdf",
 "content_base64": "JVBERi0xL...",
 "content_type": "application/pdf"
 }
 ],
 "dry_run": false // Optional - validate without sending
}

┌──────────────────┐
│ Validate Input │
│ - Email format │
│ - Header inject. │
│ - Body lengths │
└────────┬─────────┘
 │
 ▼
┌──────────────────┐
│ Enforce Policy │
│ - Recipient │
│ allowlist │
│ - Size limits │
│ - Attachment │
│ limits │
└────────┬─────────┘
 │
 ▼
┌──────────────────┐
│ Build Message │
│ - Parse attach- │
│ ments (base64) │
│ - Estimate size │
└────────┬─────────┘
 │
 ▼
 ┌──────────┐
 │ dry_run? │
 └────┬─────┘
 │
 ┌────┴────┐
 │ │
 Yes No
 │ │
 ▼ ▼
┌────────────┐ ┌──────────────┐
│ Return │ │ Send via │
│ Validation │ │ SMTP │
│ Results │ │ Transport │
└────────────┘ └──────┬───────┘
 │
 ▼
 ┌────────────────┐
 │ Return Send │
 │ Results │
 └────────────────┘

{
 "summary": "Sent message to 3 recipient(s).",
 "data": {
 "account_id": "default",
 "dry_run": false,
 "envelope": {
 "from": "sender@example.com",
 "to": ["recipient@example.com"],
 "cc": ["cc@example.com"],
 "bcc": ["bcc@example.com"]
 },
 "message_id": "<abc123@example.com>",
 "accepted": ["recipient@example.com", "cc@example.com", "bcc@example.com"],
 "rejected": []
 }
}

{
 "summary": "Validated message for 3 recipient(s).",
 "data": {
 "account_id": "default",
 "dry_run": true,
 "envelope": {
 "from": "sender@example.com",
 "to": ["recipient@example.com"],
 "cc": ["cc@example.com"],
 "bcc": ["bcc@example.com"]
 },
 "size_bytes_estimate": 12500
 }
}

{
 "summary": "Human-readable status message",
 "data": { /* Tool-specific structured data */ },
 "_meta": { /* Optional metadata (e.g., policy info) */ }
}

{
 "command": "npx",
 "args": ["-y", "@bradsjm/mail-smtp-mcp"],
 "env": {
 "MAIL_SMTP_DEFAULT_HOST": "smtp.gmail.com",
 "MAIL_SMTP_DEFAULT_PORT": "587",
 "MAIL_SMTP_DEFAULT_SECURE": "false",
 "MAIL_SMTP_DEFAULT_USER": "you@gmail.com",
 "MAIL_SMTP_DEFAULT_PASS": "your-app-password",
 "MAIL_SMTP_DEFAULT_FROM": "you@gmail.com",
 "MAIL_SMTP_SEND_ENABLED": "true"
 }
}

{
 "command": "node",
 "args": ["/path/to/mail-smtp-mcp/dist/index.js"],
 "env": {
 "MAIL_SMTP_DEFAULT_HOST": "smtp.gmail.com",
 "MAIL_SMTP_DEFAULT_USER": "you@gmail.com",
 "MAIL_SMTP_DEFAULT_PASS": "your-app-password",
 "MAIL_SMTP_SEND_ENABLED": "true"
 }
}

# Install dependencies
pnpm install

# Run in development mode (TypeScript)
pnpm dev

# Build for production
pnpm build

# Run tests
pnpm test

# Type checking
pnpm typecheck

# Linting
pnpm lint

# Format code
pnpm format:write

pnpm check