@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

encode_file

Reads a file from disk, base64-encodes it, and returns a ready-to-use attachment object. Use this before send_email rather than encoding files manually.

| Parameter | Type | Required | Description | |---|---|---|---| | path | string | yes | Absolute or relative path to the file | | content_type | string | no | MIME type override — auto-detected from extension if omitted |

Returns JSON with filename, content_type, and content (base64). Pass these fields directly as an attachment entry in send_email.

Recommended workflow for attachments:

send_email({ ..., attachments: [{ path: "/absolute/path/to/report.zip" }] })

The server reads, encodes, and detects the MIME type automatically. Binary data never passes through the agent's context.

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 — supply path or content, not both:

| Field | Type | Required | Description | |---|---|---|---| | path | string | if no content | Absolute path to file — server reads and encodes it | | content | string | if no path | Base64-encoded file data (no data: URI prefix) | | filename | string | if using content | Name shown to recipient; defaults to basename of path | | content_type | string | if using content | MIME type; auto-detected from path extension if omitted |

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.