# 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`.
```
MAIL_SMTP_DEFAULT_HOST
MAIL_SMTP_DEFAULT_PORT=587
MAIL_SMTP_DEFAULT_SECURE=false
MAIL_SMTP_DEFAULT_USER
MAIL_SMTP_DEFAULT_PASS
MAIL_SMTP_DEFAULT_FROM
```
Multiple accounts are supported by replacing `DEFAULT` with an uppercase account ID:
```
MAIL_SMTP_WORK_HOST
MAIL_SMTP_WORK_USER
MAIL_SMTP_WORK_PASS
```
### Send gate
Sending is disabled by default. Enable with:
```
MAIL_SMTP_SEND_ENABLED=true
```
### Allowlist policy (optional)
If set, only allowlisted recipients/domains can be used:
```
MAIL_SMTP_ALLOWLIST_DOMAINS=example.com,example.org
MAIL_SMTP_ALLOWLIST_ADDRESSES=alice@example.com,bob@example.org
```
### Policy/limits defaults
These defaults apply unless overridden via environment variables:
```
MAIL_SMTP_MAX_RECIPIENTS=10
MAIL_SMTP_MAX_MESSAGE_BYTES=2500000
MAIL_SMTP_MAX_ATTACHMENTS=5
MAIL_SMTP_MAX_ATTACHMENT_BYTES=2000000
MAIL_SMTP_MAX_TEXT_CHARS=20000
MAIL_SMTP_MAX_HTML_CHARS=50000
MAIL_SMTP_CONNECT_TIMEOUT_MS=10000
MAIL_SMTP_SOCKET_TIMEOUT_MS=20000
```
## 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:
```
{
"summary": "Sent message to 1 recipient(s).",
"data": {
"account_id": "default",
"dry_run": false,
"envelope": {
"from": "me@example.com",
"to": ["alice@example.com"]
},
"message_id": "<abc123@example.com>",
"accepted": ["alice@example.com"],
"rejected": []
}
}
```
## Usage
### Run locally
```
pnpm install
pnpm dev
```
### Build
```
pnpm 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:
```json
{
"command": "node",
"args": ["mail-smtp-mcp/dist/index.js"],
"env": {
"MAIL_SMTP_DEFAULT_HOST": "smtp.example.com",
"MAIL_SMTP_DEFAULT_USER": "me@example.com",
"MAIL_SMTP_DEFAULT_PASS": "app-password-or-token",
"MAIL_SMTP_SEND_ENABLED": "true"
}
}
```
### Quality gates
```
pnpm check
```
## 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.
