@agguy/email-sender-mcp

v2.0.2

Published

8 days ago

MCP server for sending SMTP email notifications

0High
0Medium
0Low

agguy

mcp model-context-protocol smtp email notification

Email Sender MCP

中文 | English: README.zh-CN.md | README.md

这是一个通过 SMTP 发送通知邮件的 MCP（Model Context Protocol）服务，支持 "Agent -> SMTP 服务器 -> 个人邮箱 -> 手机通知" 的链路。

运行环境

Node.js 18+
支持 SMTP 的邮箱账号（含密码或应用专用密码）

安装

安装依赖：

npm install

配置 SMTP（推荐使用 .env）：

copy .env.example .env

编辑 .env 填入你的 SMTP 配置。

快速开始（推荐配置）

按以下步骤完成推荐配置：

准备好 SMTP 服务器地址、端口、是否 SSL、用户名、密码。
打开 MCP 客户端配置文件。
添加下面的 email-sender 配置段。
把 SMTP 占位值替换成你的真实信息。
保存配置并重启 MCP 客户端。
用最小参数调用 send_email 验证是否正常发送。

环境变量

| 变量 | 必填 | 用途 | 示例 / 默认值 | | --- | --- | --- | --- | | SMTP_URL | 否 | SMTP 连接 URL（简化配置） | smtps://user:[email protected]:465 | | SMTP_HOST | 是* | SMTP 服务器地址 | smtp.gmail.com | | SMTP_PORT | 否 | SMTP 端口 | 465 或 587 | | SMTP_SECURE | 否 | 是否启用隐式 TLS（465 需为 true） | true / false | | SMTP_USER | 是* | SMTP 用户名 | [email protected] | | SMTP_PASS | 是* | SMTP 密码或应用专用密码 | app-password | | SMTP_FROM | 否 | 默认发件人地址 | 默认 SMTP_USER | | SMTP_TLS_REJECT_UNAUTHORIZED | 否 | 允许自签名证书（不推荐） | false | | SMTP_CONN_TIMEOUT | 否 | 连接超时（毫秒） | 15000 | | SMTP_GREETING_TIMEOUT | 否 | 问候超时（毫秒） | 15000 | | SMTP_SOCKET_TIMEOUT | 否 | Socket 超时（毫秒） | 15000 | | SMTP_RETRY_ATTEMPTS | 否 | 重试次数 | 默认 1 | | 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 (5MB) | | RESPONSE_MAX_RECIPIENTS | 否 | 响应中最大收件人数量 | 默认 50 | | RESPONSE_MODE | 否 | 响应模式（ok/minimal/summary） | 默认 ok | | LOG_LEVEL | 否 | 日志级别 | error / warn / info / debug |

*若提供 SMTP_URL，则 SMTP_HOST/SMTP_USER/SMTP_PASS 可选，但需设置 SMTP_FROM。最小配置仅需 SMTP_HOST、SMTP_USER、SMTP_PASS（或 SMTP_URL + SMTP_FROM）。

启动

npm start

该命令会通过 stdio 启动 MCP 服务，请不要在需要 stdout 输出的终端中运行。

使用 npx 启动

npx -y @agguy/email-sender-mcp@latest

MCP 客户端配置示例

以支持 stdio 的 MCP 客户端为例。

最小配置

{
  "mcpServers": {
    "email-sender": {
      "command": "node",
      "args": ["/absolute/path/to/email-sender-mcp/src/server.js"]
    }
  }
}

最大配置（展示全部参数）

{
  "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": "[email protected]",
        "SMTP_PASS": "your-app-password",
        "SMTP_FROM": "[email protected]",
        "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"
      }
    }
  }
}

请确保 MCP 进程能读取到环境变量。若客户端支持传递环境变量，请在客户端配置；否则请在项目目录下准备 .env 并从该目录启动客户端。

工具：send_email

参数用途

| 参数 | 用途 | | --- | --- | | to | 收件人（字符串 / 数组 / { name, address }） | | cc / bcc / replyTo | 可选收件人（同 to 格式） | | from | 覆盖发件人地址 | | subject | 邮件主题 | | text | 纯文本正文 | | html | HTML 正文 | | template | 模板内容与变量 | | headers | 自定义头信息 | | priority | 优先级 high / normal / low | | attachments | 附件（路径或内容） | | retry | 重试策略覆盖 | | smtp | 单次调用 SMTP 覆盖 | | requestId | 请求追踪 ID | | responseMode | 响应模式：ok / minimal / summary |

最小示例

{
  "to": "[email protected]",
  "subject": "Hello",
  "text": "Agent notification."
}

多收件人（数组）

{
  "to": ["[email protected]", "[email protected]"],
  "subject": "Hello",
  "text": "Agent notification."
}

地址对象（name + address）

{
  "to": { "name": "Agguy", "address": "[email protected]" },
  "subject": "Hello",
  "text": "Agent notification."
}

模板示例

{
  "to": "[email protected]",
  "subject": "Hello",
  "template": {
    "text": "Hi {{name}}, build {{build}} completed.",
    "variables": {
      "name": "Agguy",
      "build": "42"
    }
  }
}

附件、头信息、优先级

{
  "to": "[email protected]",
  "subject": "Report",
  "text": "See attachment.",
  "priority": "high",
  "headers": {
    "X-Project": "email-sender-mcp"
  },
  "attachments": [
    {
      "filename": "report.txt",
      "content": "Hello",
      "encoding": "utf-8"
    }
  ]
}

单次调用覆盖 SMTP

{
  "to": "[email protected]",
  "subject": "Hello",
  "text": "Agent notification.",
  "smtp": {
    "host": "smtp.example.com",
    "port": 587,
    "secure": false,
    "user": "[email protected]",
    "pass": "your-password"
  }
}

重试覆盖 + requestId

{
  "requestId": "notify-42",
  "to": "[email protected]",
  "subject": "Hello",
  "text": "Agent notification.",
  "retry": {
    "attempts": 3,
    "delayMs": 500,
    "backoffFactor": 2,
    "maxDelayMs": 5000
  }
}

最大示例（展示全部参数）

{
  "requestId": "notify-42",
  "to": [
    { "name": "Agguy", "address": "[email protected]" },
    "[email protected]"
  ],
  "cc": "[email protected]",
  "bcc": [{ "name": "Audit", "address": "[email protected]" }],
  "replyTo": { "name": "Support", "address": "[email protected]" },
  "from": "[email protected]",
  "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:[email protected]:465",
    "host": "smtp.example.com",
    "port": 465,
    "secure": true,
    "user": "[email protected]",
    "pass": "your-password",
    "connectionTimeout": 15000,
    "greetingTimeout": 15000,
    "socketTimeout": 15000,
    "tlsRejectUnauthorized": true
  }
}

响应模式

ok: 完全成功仅返回 {"ok": true}，如有拒收则返回错误信息。
minimal: 返回 messageId、计数与 attempts。
summary: 返回计数及 accepted/rejected 列表（可能被截断）。

备注

text 或 html 至少提供一个，也可以用 template.text/template.html 生成内容。
生产环境建议使用环境变量，避免在工具调用里直接传凭据。
地址字段支持逗号分隔字符串或数组形式。
响应为 JSON 字符串，包含 messageId、accepted、rejected 等信息。若收件人过多，会按 RESPONSE_MAX_RECIPIENTS 截断。
当 RESPONSE_MODE=ok（或 responseMode: "ok"）时，完全成功仅返回 {"ok": true}；若有拒收，则返回错误信息。
附件路径会受 ATTACHMENT_ALLOWED_DIRS 限制，大小由 ATTACHMENT_MAX_BYTES 控制。