email-sender
MCP server for sending SMTP email notifications
Installation
npx @agguy/email-sender-mcpAsk AI about email-sender
Powered by Claude · Grounded in docs
I know everything about email-sender. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Email Sender MCP
English | Chinese: README.md | README.zh-CN.md
An MCP (Model Context Protocol) server that exposes a send_email tool for SMTP
notifications. This enables an "Agent -> SMTP server -> personal email -> phone
notification" workflow.
Table of Contents
- Getting Started (Recommended)
- Environment Variables
- MCP Client Configuration
- Tool: send_email
- Response Modes
- Notes
Requirements
- Node.js 18+
- An SMTP-capable email account (and credentials or an app password)
Setup
- Install dependencies:
npm install
- Configure SMTP credentials (recommended via
.env):
copy .env.example .env
Edit .env with your SMTP settings.
Getting Started (Recommended)
Follow these steps to complete the recommended MCP configuration:
- Pick your SMTP provider settings (host/port/secure/user/pass).
- Open your MCP client config file.
- Add the
email-senderserver entry below. - Replace the placeholder SMTP values with your real credentials.
- Save the config and restart your MCP client.
- Call the
send_emailtool with a minimal payload to verify.
Environment variables
| Variable | Required | Purpose | Example / Default |
|---|---|---|---|
SMTP_URL | No | SMTP connection URL (simplified config) | smtps://user:pass@smtp.example.com:465 |
SMTP_HOST | Yes* | SMTP server hostname | smtp.gmail.com |
SMTP_PORT | No | SMTP server port | 465 or 587 |
SMTP_SECURE | No | Enable implicit TLS (true for 465) | true / false |
SMTP_USER | Yes* | SMTP username | user@example.com |
SMTP_PASS | Yes* | SMTP password or app password | app-password |
SMTP_FROM | No | Default From address | Defaults to SMTP_USER |
SMTP_TLS_REJECT_UNAUTHORIZED | No | Allow self-signed certs (not recommended) | false |
SMTP_CONN_TIMEOUT | No | Connection timeout (ms) | 15000 |
SMTP_GREETING_TIMEOUT | No | Greeting timeout (ms) | 15000 |
SMTP_SOCKET_TIMEOUT | No | Socket timeout (ms) | 15000 |
SMTP_RETRY_ATTEMPTS | No | Retry attempts | Default: 1 |
SMTP_RETRY_DELAY_MS | No | Initial retry delay (ms) | Default: 500 |
SMTP_RETRY_BACKOFF | No | Retry backoff multiplier | Default: 2 |
SMTP_RETRY_MAX_DELAY_MS | No | Max retry delay (ms) | Default: 5000 |
ATTACHMENT_ALLOWED_DIRS | No | Allowed dirs for attachment paths | /path/to/uploads;/path/to/reports |
ATTACHMENT_MAX_BYTES | No | Max attachment size (bytes) | Default: 5242880 (5MB) |
RESPONSE_MAX_RECIPIENTS | No | Max recipients returned in responses | Default: 50 |
RESPONSE_MODE | No | Response verbosity (ok/minimal/summary) | Default: ok |
LOG_LEVEL | No | Logging verbosity | error / warn / info / debug |
*If SMTP_URL is provided, SMTP_HOST/SMTP_USER/SMTP_PASS are optional. In that case, make sure SMTP_FROM is set.
Minimal required config is SMTP_HOST, SMTP_USER, and SMTP_PASS (or SMTP_URL + SMTP_FROM).
Run
npm start
This starts the MCP server over stdio. Do not run it in a terminal where stdout is needed for other output.
Run via npx
npx -y @agguy/email-sender-mcp@latest
MCP client configuration
Use an MCP client that supports stdio, and point it to this server.
Minimal configuration
{
"mcpServers": {
"email-sender": {
"command": "node",
"args": ["/absolute/path/to/email-sender-mcp/src/server.js"]
}
}
}
Recommended configuration
{
"mcpServers": {
"email-sender": {
"command": "npx",
"args": ["-y", "--quiet", "@agguy/email-sender-mcp@latest"],
"env": {
"SMTP_HOST": "smtp.example.com",
"SMTP_PORT": "465",
"SMTP_SECURE": "true",
"SMTP_USER": "your-email@example.com",
"SMTP_PASS": "your-app-password",
"SMTP_FROM": "your-email@example.com"
}
}
}
}
Maximal configuration (all parameters)
{
"mcpServers": {
"email-sender": {
"command": "node",
"args": ["/absolute/path/to/email-sender-mcp/src/server.js"],
"env": {
"SMTP_HOST": "smtp.example.com",
"SMTP_PORT": "465",
"SMTP_SECURE": "true",
"SMTP_USER": "your-email@example.com",
"SMTP_PASS": "your-app-password",
"SMTP_FROM": "your-email@example.com",
"SMTP_TLS_REJECT_UNAUTHORIZED": "true",
"SMTP_CONN_TIMEOUT": "15000",
"SMTP_GREETING_TIMEOUT": "15000",
"SMTP_SOCKET_TIMEOUT": "15000",
"SMTP_RETRY_ATTEMPTS": "3",
"SMTP_RETRY_DELAY_MS": "500",
"SMTP_RETRY_BACKOFF": "2",
"SMTP_RETRY_MAX_DELAY_MS": "5000",
"ATTACHMENT_ALLOWED_DIRS": "/path/to/uploads;/path/to/reports",
"ATTACHMENT_MAX_BYTES": "5242880",
"RESPONSE_MAX_RECIPIENTS": "50",
"LOG_LEVEL": "info"
}
}
}
}
Ensure the environment variables are available to the MCP process. If your MCP
client supports passing env vars, set them there; otherwise run the client from
the project directory with a .env file.
Tool: send_email
Parameters
| Field | Purpose |
|---|---|
to | Recipients (string, array, or { name, address }) |
cc / bcc / replyTo | Optional recipients (same formats as to) |
from | Override sender address |
subject | Email subject |
text | Plain-text body |
html | HTML body |
template | Template with text/html and variables |
headers | Custom headers |
priority | high / normal / low |
attachments | Attachments (path or content) |
retry | Retry policy overrides |
smtp | Per-call SMTP overrides |
requestId | Optional trace id |
responseMode | Response mode: ok, minimal, summary |
Minimal example
{
"to": "me@example.com",
"subject": "Hello",
"text": "Agent notification."
}
Multiple recipients (array)
{
"to": ["me@example.com", "team@example.com"],
"subject": "Hello",
"text": "Agent notification."
}
Address object (name + address)
{
"to": { "name": "Agguy", "address": "me@example.com" },
"subject": "Hello",
"text": "Agent notification."
}
Template example
{
"to": "me@example.com",
"subject": "Hello",
"template": {
"text": "Hi {{name}}, build {{build}} completed.",
"variables": {
"name": "Agguy",
"build": "42"
}
}
}
Attachments, headers, priority
{
"to": "me@example.com",
"subject": "Report",
"text": "See attachment.",
"priority": "high",
"headers": {
"X-Project": "email-sender-mcp"
},
"attachments": [
{
"filename": "report.txt",
"content": "Hello",
"encoding": "utf-8"
}
]
}
Per-call SMTP override
{
"to": "me@example.com",
"subject": "Hello",
"text": "Agent notification.",
"smtp": {
"host": "smtp.example.com",
"port": 587,
"secure": false,
"user": "your-email@example.com",
"pass": "your-password"
}
}
Retry override + requestId
{
"requestId": "notify-42",
"to": "me@example.com",
"subject": "Hello",
"text": "Agent notification.",
"retry": {
"attempts": 3,
"delayMs": 500,
"backoffFactor": 2,
"maxDelayMs": 5000
}
}
Maximum example (all parameters)
{
"requestId": "notify-42",
"to": [
{ "name": "Agguy", "address": "me@example.com" },
"team@example.com"
],
"cc": "cc@example.com",
"bcc": [{ "name": "Audit", "address": "audit@example.com" }],
"replyTo": { "name": "Support", "address": "support@example.com" },
"from": "sender@example.com",
"subject": "Build report",
"html": "<b>Build completed</b>",
"template": {
"text": "Hi {{name}}, build {{build}} completed.",
"variables": { "name": "Agguy", "build": "42" }
},
"headers": { "X-Project": "email-sender-mcp" },
"priority": "high",
"attachments": [
{ "filename": "note.txt", "content": "Hello", "encoding": "utf-8" },
{ "path": "/path/to/reports/report.pdf" }
],
"retry": {
"attempts": 3,
"delayMs": 500,
"backoffFactor": 2,
"maxDelayMs": 5000
},
"responseMode": "summary",
"smtp": {
"url": "smtps://user:pass@smtp.example.com:465",
"host": "smtp.example.com",
"port": 465,
"secure": true,
"user": "your-email@example.com",
"pass": "your-password",
"connectionTimeout": 15000,
"greetingTimeout": 15000,
"socketTimeout": 15000,
"tlsRejectUnauthorized": true
}
}
Response Modes
ok: return only{"ok": true}on full success. If any recipient is rejected, an error payload is returned.minimal: return counts and identifiers (messageId, counts, attempts).summary: return counts plusaccepted/rejectedlists (may be truncated).
Notes
textorhtmlis required. You can also usetemplate.textortemplate.htmlto generate content.- For production, prefer environment variables over passing credentials in tool calls.
- Address fields accept comma-separated strings or arrays of email addresses.
- Responses are JSON strings with
messageId,accepted, andrejecteddetails. Large recipient lists may be truncated based onRESPONSE_MAX_RECIPIENTS. - When
RESPONSE_MODE=ok(orresponseMode: "ok"), a full success returns only{"ok": true}. If any recipient is rejected, an error payload is returned. - Attachment paths are limited by
ATTACHMENT_ALLOWED_DIRS, and size is capped byATTACHMENT_MAX_BYTES.
