mail-smtp-mcp

TypeScript MCP (stdio) server for sending email via SMTP with a compact, LLM-optimized tool surface.

Overview

This server exposes outcome-oriented tools to validate SMTP accounts and send outbound email with strict policy controls. Responses are JSON-encoded text and include:

• summary: concise human-readable summary

• data: structured payload aligned to the tool contract

• _meta: optional metadata (e.g., policy limits)

Capabilities

Read-only

• List configured SMTP accounts (non-secret metadata)

• Verify SMTP connectivity/authentication (no email sent)

Send (gated)

• Send outbound email with text/HTML bodies

• Optional attachments (bounded)

• dry_run to validate inputs and policy without sending

Tools

mail_smtp_list_accounts

List configured SMTP accounts.

mail_smtp_verify_account

Verify a configured SMTP account can connect/authenticate.

Inputs include:

• account_id (default: default)

mail_smtp_send_message

Send or validate an outbound email via SMTP.

Inputs include:

• account_id (default: default)

• from (optional; falls back to account default)

• to, cc, bcc (string or string[])

• reply_to (optional)

• subject (required; header-injection safe)

• text_body and/or html_body (at least one required)

• attachments (optional; base64 content)

• dry_run (optional; default false)

Configuration

Account configuration is provided via environment variables. This server also loads a local .env file (if present) using dotenv. Do not commit secrets. An example is provided in .env.sample.

If you only configure the default account, you can omit account_id in tool calls; it defaults to default.

Multiple accounts are supported by replacing DEFAULT with an uppercase account ID:

Send gate

Sending is disabled by default. Enable with:

Allowlist policy (optional)

If set, only allowlisted recipients/domains can be used:

Policy/limits defaults

These defaults apply unless overridden via environment variables:

Response shape (JSON text)

Many MCP clients expect content items to be type: "text" (and do not accept a JSON content type). This server returns a single text content item whose text is a JSON object:

Usage

Run locally

Build

Chat Application Integration (stdio spawn command)

Many MCP-enabled chat applications run stdio servers by spawning a process from an executable command. These are common ways to invoke this server:

Option 1: Run via npx (published package)

• command: npx

• args: -y mail-smtp-mcp

Option 2: Run from this repo (dev, no build)

• command: pnpm

• args: -C /Users/jonathan/Code/Projects/mail-smtp-mcp dev

Option 3: Run from this repo (built)

1. Build once:

   pnpm -C /Users/jonathan/Code/Projects/mail-smtp-mcp build

2. Spawn:

• command: node

• args: /Users/jonathan/Code/Projects/mail-smtp-mcp/dist/index.js

Option 4: Install globally (true executable)

1. Install:

   pnpm -g add /Users/jonathan/Code/Projects/mail-smtp-mcp

2. Spawn:

• command: mail-smtp-mcp

Example MCP server config

Exact configuration keys vary by chat application, but the shape usually looks like:

Quality gates

Notes

• Sending is gated by MAIL_SMTP_SEND_ENABLED=true.

• Use dry_run to validate payloads without sending.

• Inputs reject header injection characters and enforce size limits.

• Do not log or return credentials; outputs contain non-secret metadata only.