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

1. Install dependencies:

npm install

2. 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:

1. Pick your SMTP provider settings (host/port/secure/user/pass).
2. Open your MCP client config file.
3. Add the email-sender server entry below.
4. Replace the placeholder SMTP values with your real credentials.
5. Save the config and restart your MCP client.
6. Call the send_email tool 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 plus accepted/rejected lists (may be truncated).

Notes

• text or html is required. You can also use template.text or template.html to 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, and rejected details. Large recipient lists may be truncated based on RESPONSE_MAX_RECIPIENTS.
• When RESPONSE_MODE=ok (or responseMode: "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 by ATTACHMENT_MAX_BYTES.