@teamnetwork-nz/smtp-mcp-server

An MCP server that lets AI agents send email via any SMTP relay. Recipient restrictions, sender identity, and SMTP credentials are all enforced server-side — an agent cannot override them.

Features

• Send plain-text or HTML email
• Attach files (base64-encoded)
• CC and BCC support
• Restrict recipients to allowed domains and/or explicit addresses
• Configurable sender name and address
• Works with any SMTP server (Gmail, SendGrid, Mailgun, self-hosted, unauthenticated relay, etc.)
• health tool for live connection testing
• Built-in usage resource agents can read to understand available options

Install

npm install -g @teamnetwork-nz/smtp-mcp-server

Or run directly with npx (no global install needed):

npx @teamnetwork-nz/smtp-mcp-server

Build from source

git clone <repo>
cd smtp-mcp-server
npm install && npm run build

Configuration

All configuration is via environment variables (loaded from .env if present).

| Variable | Required | Description | |---|---|---| | SMTP_HOST | yes | SMTP relay hostname | | SMTP_PORT | no | Port — default 587 | | SMTP_SECURE | no | "true" for port 465 implicit TLS; otherwise STARTTLS | | SMTP_IGNORE_TLS | no | "true" to disable TLS entirely — plain SMTP, e.g. port 25 internal relay | | SMTP_USER | no | SMTP auth username — omit for unauthenticated relays | | SMTP_PASS | no | SMTP auth password — omit for unauthenticated relays | | SMTP_FROM_ADDRESS | yes | Envelope From address | | SMTP_FROM_NAME | no | Display name — defaults to SMTP_FROM_ADDRESS | | ALLOWED_DOMAINS | no | Comma-separated domains, e.g. acme.com,partner.org | | ALLOWED_ADDRESSES | no | Comma-separated explicit addresses |

Restriction logic: a recipient is permitted if its domain matches ALLOWED_DOMAINS or it appears in ALLOWED_ADDRESSES. All addresses across to, cc, and bcc are checked — a single blocked address rejects the whole request. If neither variable is set, all addresses are permitted (not recommended for production).

Claude Code Integration

Add to your .claude/mcp_config.json (or claude_desktop_config.json):

{
  "mcpServers": {
    "smtp": {
      "command": "npx",
      "args": ["-y", "@teamnetwork-nz/smtp-mcp-server"],
      "env": {
        "SMTP_HOST": "smtp.example.com",
        "SMTP_PORT": "587",
        "SMTP_USER": "[email protected]",
        "SMTP_PASS": "your-password",
        "SMTP_FROM_ADDRESS": "[email protected]",
        "SMTP_FROM_NAME": "My Agent",
        "ALLOWED_DOMAINS": "example.com"
      }
    }
  }
}

For an unauthenticated internal relay, omit SMTP_USER and SMTP_PASS.

Tools

health

No parameters. Performs a live TCP+SMTP handshake against the configured server and returns the active configuration summary.

connection:   OK (42 ms)
smtp_host:    smtp.example.com:587
tls:          STARTTLS
auth:         authenticated as [email protected]
from:         "My Agent" <[email protected]>
restrictions: domains: example.com

Returns isError: true if the connection test fails, with the SMTP error message included.

send_email

| Parameter | Type | Required | Description | |---|---|---|---| | to | string | string[] | yes | Recipient(s) | | subject | string | yes | Subject line | | body | string | yes | Body content | | body_type | "text" | "html" | no | Default: "text" | | cc | string | string[] | no | CC recipient(s) | | bcc | string | string[] | no | BCC recipient(s) | | attachments | Attachment[] | no | Files to attach |

Attachment object:

| Field | Type | Description | |---|---|---| | filename | string | Name shown to recipient | | content | string | Base64-encoded file data | | content_type | string | MIME type, e.g. application/pdf |

Resource: smtp://server/usage

A plain-text usage guide populated with the server's live configuration (sender identity, SMTP endpoint, active restrictions, full tool reference). Agents can read this resource to understand what options are available without calling any tools.

Local Testing with Mailpit

Mailpit is a lightweight local SMTP catcher — no credentials required:

# macOS
brew install mailpit && mailpit

# Windows (scoop)
scoop install mailpit && mailpit

Set SMTP_HOST=localhost, SMTP_PORT=1025, omit SMTP_USER/SMTP_PASS. View caught emails at http://localhost:8025.