# mail-smtp-mcp
A TypeScript MCP (Model Context Protocol) server for sending email via SMTP, designed for code agents. Exposes a compact, LLM-optimized tool surface with strict policy controls and validation.
## Quick Start
### Primary Usage (Recommended)
Run directly via npx with your MCP client:
```bash
npx -y @bradsjm/mail-smtp-mcp
```
Configure the required environment variables before starting (see [Configuration](#configuration) below).
### Local Development
```bash
pnpm install
pnpm dev
```
Build for production:
```bash
pnpm build
```
## Configuration
The server loads configuration from environment variables. A local `.env` file is also supported via `dotenv` (do not commit secrets).
### Account Configuration
Configure one or more SMTP accounts using the following pattern:
```
MAIL_SMTP_<ACCOUNT_ID>_<SETTING>=value
```
| Setting | Required | Default | Description |
|---------|----------|---------|-------------|
| `HOST` | Yes | - | SMTP server hostname |
| `PORT` | No | 587 (if SECURE=false), 465 (if SECURE=true) | SMTP server port |
| `SECURE` | No | `false` | Use SSL/TLS (true) or STARTTLS (false) |
| `USER` | Yes | - | SMTP authentication username |
| `PASS` | Yes | - | SMTP authentication password |
| `FROM` | No | - | Default sender email address |
**Example - Default Account:**
```bash
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
```
**Example - Multiple Accounts:**
```bash
# 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
```
### Send Gate
Sending is **disabled by default** for security. Enable with:
```bash
MAIL_SMTP_SEND_ENABLED=true
```
### Allowlist Policy (Optional)
Restrict recipients to specific domains or email addresses:
```bash
MAIL_SMTP_ALLOWLIST_DOMAINS=example.com,example.org
MAIL_SMTP_ALLOWLIST_ADDRESSES=alice@example.com,bob@example.org
```
### Policy Limits
Configure operational limits (defaults shown):
| Variable | Default | Description |
|----------|---------|-------------|
| `MAIL_SMTP_MAX_RECIPIENTS` | 10 | Maximum recipients per message |
| `MAIL_SMTP_MAX_MESSAGE_BYTES` | 2,500,000 | Maximum total message size (~2.4 MB) |
| `MAIL_SMTP_MAX_ATTACHMENTS` | 5 | Maximum number of attachments |
| `MAIL_SMTP_MAX_ATTACHMENT_BYTES` | 2,000,000 | Maximum size per attachment (~1.9 MB) |
| `MAIL_SMTP_MAX_TEXT_CHARS` | 20,000 | Maximum characters in plain text body |
| `MAIL_SMTP_MAX_HTML_CHARS` | 50,000 | Maximum characters in HTML body |
| `MAIL_SMTP_CONNECT_TIMEOUT_MS` | 10,000 | SMTP connection timeout (ms) |
| `MAIL_SMTP_SOCKET_TIMEOUT_MS` | 20,000 | SMTP socket timeout (ms) |
## Tools Overview
| Tool | Purpose | Requires Send Enabled? |
|------|---------|----------------------|
| `smtp_list_accounts` | List configured SMTP accounts | No |
| `smtp_verify_account` | Verify SMTP connectivity without sending email | No |
| `smtp_send_message` | Send or validate an outbound email | Yes (unless dry_run) |
## Tool Details
### `smtp_list_accounts`
Lists configured SMTP accounts with non-sensitive metadata.
**Input:**
```json
{
"account_id": "default" // Optional - filter by specific account
}
```
**Response:**
```json
{
"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
}
}
}
```
### `smtp_verify_account`
Verifies that an SMTP account can connect and authenticate without sending an email.
**Input:**
```json
{
"account_id": "default" // Defaults to "default"
}
```
**Verification Flow:**
```
┌─────────────────┐
│ Load Account │
│ Config │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Create SMTP │
│ Transport │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Verify Connect │
│ & Authenticate │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Return Status │
│ (ok / error) │
└─────────────────┘
```
**Response:**
```json
{
"summary": "SMTP account default verified successfully.",
"data": {
"account_id": "default",
"status": "ok"
}
}
```
### `smtp_send_message`
Sends or validates an outbound email via SMTP with comprehensive validation.
**Input:**
```json
{
"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
}
```
**Send Flow:**
```
┌──────────────────┐
│ 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 │
└────────────────┘
```
**Response (Success):**
```json
{
"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": []
}
}
```
**Response (Dry Run):**
```json
{
"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
}
}
```
## Response Format
All tool responses use a consistent JSON structure returned as MCP text content:
```
{
"summary": "Human-readable status message",
"data": { /* Tool-specific structured data */ },
"_meta": { /* Optional metadata (e.g., policy info) */ }
}
```
## Hard Maximum Limits
The following absolute upper bounds cannot be exceeded regardless of policy settings:
| Resource | Hard Limit |
|----------|------------|
| Recipients per message | 50 |
| Attachments per message | 10 |
| Attachment size | 5,000,000 bytes (~4.8 MB) |
| Plain text body characters | 100,000 |
| HTML body characters | 200,000 |
| Subject characters | 256 |
## Security Notes
- **No HTTP Transport**: This server only supports stdio transport for security. HTTP endpoints are intentionally not exposed.
- **Credential Handling**: SMTP credentials are never logged or returned in tool responses.
- **Header Injection Protection**: All email addresses and subject fields are validated to reject CR/LF characters that could be used for header injection.
- **Filename Safety**: Attachment filenames are validated to prevent path traversal attacks.
- **Send Gate**: Sending is disabled by default and must be explicitly enabled via `MAIL_SMTP_SEND_ENABLED=true`.
- **Dry Run Mode**: Use `dry_run: true` to validate messages and policies without actually sending emails.
## MCP Client Integration
### Standard npx Configuration
Most MCP-enabled applications can spawn this server using:
```json
{
"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"
}
}
```
### Development Configuration
For local development without publishing:
```json
{
"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"
}
}
```
## Development
```bash
# 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
```
Run all quality checks:
```bash
pnpm check
```
## License
See LICENSE file for details.
