@teamnetwork-nz/smtp-mcp-server 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/.env.example ADDED
@@ -0,0 +1,16 @@
1
+ # SMTP relay settings
2
+ SMTP_HOST=smtp.example.com
3
+ SMTP_PORT=587
4
+ SMTP_SECURE=false # set to "true" for port 465 implicit TLS
5
+ SMTP_USER=user@example.com # optional — omit for unauthenticated relays
6
+ SMTP_PASS=your-password-here # optional — omit for unauthenticated relays
7
+
8
+ # Sender identity shown in the From header
9
+ SMTP_FROM_ADDRESS=agent@example.com
10
+ SMTP_FROM_NAME=My Agent # optional, defaults to SMTP_FROM_ADDRESS
11
+
12
+ # Recipient restrictions (at least one recommended for production)
13
+ # An address passes if it matches ANY rule — domain OR explicit address.
14
+ # If both variables are empty, all addresses are permitted (open mode).
15
+ ALLOWED_DOMAINS=example.com,partner.org # comma-separated domains
16
+ ALLOWED_ADDRESSES=external@other.com # comma-separated explicit addresses
package/README.md ADDED
@@ -0,0 +1,110 @@
1
+ # @teamnetwork-nz/smtp-mcp-server
2
+
3
+ An MCP server that lets AI agents send email via any SMTP relay. Recipient restrictions are enforced server-side — an agent cannot bypass them.
4
+
5
+ ## Features
6
+
7
+ - Send plain-text or HTML email
8
+ - Attach files (base64-encoded)
9
+ - CC and BCC support
10
+ - Restrict recipients to allowed domains and/or explicit addresses
11
+ - Configurable sender name and address
12
+ - Works with any SMTP server (Gmail, SendGrid, Mailgun, self-hosted, unauthenticated relay, etc.)
13
+
14
+ ## Install
15
+
16
+ ```bash
17
+ npm install -g @teamnetwork-nz/smtp-mcp-server
18
+ ```
19
+
20
+ Or run directly with npx (no install needed):
21
+
22
+ ```bash
23
+ npx @teamnetwork-nz/smtp-mcp-server
24
+ ```
25
+
26
+ ### Build from source
27
+
28
+ ```bash
29
+ git clone <repo>
30
+ cd smtp-mcp-server
31
+ npm install && npm run build
32
+ ```
33
+
34
+ ## Configuration
35
+
36
+ All configuration is via environment variables (loaded from `.env` if present).
37
+
38
+ | Variable | Required | Description |
39
+ |---|---|---|
40
+ | `SMTP_HOST` | yes | SMTP relay hostname |
41
+ | `SMTP_PORT` | no | Port — default `587` |
42
+ | `SMTP_SECURE` | no | `"true"` for port 465 implicit TLS; default STARTTLS |
43
+ | `SMTP_USER` | no | SMTP auth username — omit for unauthenticated relays |
44
+ | `SMTP_PASS` | no | SMTP auth password — omit for unauthenticated relays |
45
+ | `SMTP_FROM_ADDRESS` | yes | Envelope From address |
46
+ | `SMTP_FROM_NAME` | no | Display name — defaults to `SMTP_FROM_ADDRESS` |
47
+ | `ALLOWED_DOMAINS` | no | Comma-separated domains, e.g. `acme.com,partner.org` |
48
+ | `ALLOWED_ADDRESSES` | no | Comma-separated explicit addresses |
49
+
50
+ **Restriction logic:** a recipient is permitted if its domain matches `ALLOWED_DOMAINS` **or** it appears in `ALLOWED_ADDRESSES`. If neither is set, all addresses are permitted — not recommended for production.
51
+
52
+ ## Claude Code Integration
53
+
54
+ Add to your `.claude/mcp_config.json` (or `claude_desktop_config.json`):
55
+
56
+ ```json
57
+ {
58
+ "mcpServers": {
59
+ "smtp": {
60
+ "command": "npx",
61
+ "args": ["-y", "@teamnetwork-nz/smtp-mcp-server"],
62
+ "env": {
63
+ "SMTP_HOST": "smtp.example.com",
64
+ "SMTP_PORT": "587",
65
+ "SMTP_USER": "user@example.com",
66
+ "SMTP_PASS": "your-password",
67
+ "SMTP_FROM_ADDRESS": "agent@example.com",
68
+ "SMTP_FROM_NAME": "My Agent",
69
+ "ALLOWED_DOMAINS": "example.com"
70
+ }
71
+ }
72
+ }
73
+ }
74
+ ```
75
+
76
+ For an unauthenticated internal relay, omit `SMTP_USER` and `SMTP_PASS`.
77
+
78
+ ## Tool: `send_email`
79
+
80
+ | Parameter | Type | Required | Description |
81
+ |---|---|---|---|
82
+ | `to` | string \| string[] | yes | Recipient(s) |
83
+ | `subject` | string | yes | Subject line |
84
+ | `body` | string | yes | Body content |
85
+ | `body_type` | `"text"` \| `"html"` | no | Default: `"text"` |
86
+ | `cc` | string \| string[] | no | CC recipient(s) |
87
+ | `bcc` | string \| string[] | no | BCC recipient(s) |
88
+ | `attachments` | Attachment[] | no | Files to attach |
89
+
90
+ **Attachment object:**
91
+
92
+ | Field | Type | Description |
93
+ |---|---|---|
94
+ | `filename` | string | Name shown to recipient |
95
+ | `content` | string | Base64-encoded file data |
96
+ | `content_type` | string | MIME type, e.g. `application/pdf` |
97
+
98
+ ## Local Testing with Mailpit
99
+
100
+ [Mailpit](https://mailpit.axllent.org/) is a lightweight local SMTP catcher:
101
+
102
+ ```bash
103
+ # macOS
104
+ brew install mailpit && mailpit
105
+
106
+ # Windows (scoop)
107
+ scoop install mailpit && mailpit
108
+ ```
109
+
110
+ Then set `SMTP_HOST=localhost`, `SMTP_PORT=1025`, and leave `SMTP_USER`/`SMTP_PASS` as dummy values. View caught emails at http://localhost:8025.
package/dist/config.js ADDED
@@ -0,0 +1,70 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.config = void 0;
7
+ const dotenv_1 = __importDefault(require("dotenv"));
8
+ const zod_1 = require("zod");
9
+ dotenv_1.default.config();
10
+ const configSchema = zod_1.z.object({
11
+ smtp: zod_1.z.object({
12
+ host: zod_1.z.string().min(1, "SMTP_HOST is required"),
13
+ port: zod_1.z.coerce.number().int().min(1).max(65535).default(587),
14
+ secure: zod_1.z
15
+ .string()
16
+ .transform((v) => v.toLowerCase() === "true")
17
+ .default(false),
18
+ user: zod_1.z.string().min(1).optional(),
19
+ pass: zod_1.z.string().min(1).optional(),
20
+ }),
21
+ from: zod_1.z.object({
22
+ address: zod_1.z.string().email("SMTP_FROM_ADDRESS must be a valid email"),
23
+ name: zod_1.z.string().optional(),
24
+ }),
25
+ restrictions: zod_1.z.object({
26
+ allowedDomains: zod_1.z.array(zod_1.z.string()).default([]),
27
+ allowedAddresses: zod_1.z.array(zod_1.z.string().email()).default([]),
28
+ }),
29
+ });
30
+ function parseList(value) {
31
+ if (!value)
32
+ return [];
33
+ return value
34
+ .split(",")
35
+ .map((s) => s.trim())
36
+ .filter(Boolean);
37
+ }
38
+ function loadConfig() {
39
+ const raw = {
40
+ smtp: {
41
+ host: process.env.SMTP_HOST,
42
+ port: process.env.SMTP_PORT,
43
+ secure: process.env.SMTP_SECURE,
44
+ user: process.env.SMTP_USER,
45
+ pass: process.env.SMTP_PASS,
46
+ },
47
+ from: {
48
+ address: process.env.SMTP_FROM_ADDRESS,
49
+ name: process.env.SMTP_FROM_NAME,
50
+ },
51
+ restrictions: {
52
+ allowedDomains: parseList(process.env.ALLOWED_DOMAINS),
53
+ allowedAddresses: parseList(process.env.ALLOWED_ADDRESSES),
54
+ },
55
+ };
56
+ const result = configSchema.safeParse(raw);
57
+ if (!result.success) {
58
+ const messages = result.error.issues
59
+ .map((i) => ` ${i.path.join(".")}: ${i.message}`)
60
+ .join("\n");
61
+ console.error(`Configuration error:\n${messages}`);
62
+ process.exit(1);
63
+ }
64
+ const config = result.data;
65
+ if (!config.from.name) {
66
+ config.from.name = config.from.address;
67
+ }
68
+ return config;
69
+ }
70
+ exports.config = loadConfig();
package/dist/email.js ADDED
@@ -0,0 +1,40 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.createTransport = createTransport;
7
+ exports.sendEmail = sendEmail;
8
+ const nodemailer_1 = __importDefault(require("nodemailer"));
9
+ function createTransport(smtpConfig) {
10
+ return nodemailer_1.default.createTransport({
11
+ host: smtpConfig.host,
12
+ port: smtpConfig.port,
13
+ secure: smtpConfig.secure,
14
+ ...(smtpConfig.user && smtpConfig.pass
15
+ ? { auth: { user: smtpConfig.user, pass: smtpConfig.pass } }
16
+ : {}),
17
+ });
18
+ }
19
+ async function sendEmail(transport, from, options) {
20
+ const message = {
21
+ from: `"${from.name}" <${from.address}>`,
22
+ to: options.to,
23
+ subject: options.subject,
24
+ cc: options.cc,
25
+ bcc: options.bcc,
26
+ attachments: options.attachments?.map((a) => ({
27
+ filename: a.filename,
28
+ content: Buffer.from(a.content, "base64"),
29
+ contentType: a.content_type,
30
+ })),
31
+ };
32
+ if (options.body_type === "html") {
33
+ message.html = options.body;
34
+ }
35
+ else {
36
+ message.text = options.body;
37
+ }
38
+ const info = await transport.sendMail(message);
39
+ return { messageId: info.messageId };
40
+ }
package/dist/index.js ADDED
@@ -0,0 +1,96 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
4
+ const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
5
+ const zod_1 = require("zod");
6
+ const config_js_1 = require("./config.js");
7
+ const restrictions_js_1 = require("./restrictions.js");
8
+ const email_js_1 = require("./email.js");
9
+ const transport = (0, email_js_1.createTransport)(config_js_1.config.smtp);
10
+ const server = new mcp_js_1.McpServer({
11
+ name: "smtp-mcp",
12
+ version: "1.0.0",
13
+ });
14
+ const attachmentSchema = zod_1.z.object({
15
+ filename: zod_1.z.string().min(1),
16
+ content: zod_1.z.string().min(1).describe("Base64-encoded file content"),
17
+ content_type: zod_1.z.string().min(1).describe("MIME type, e.g. application/pdf"),
18
+ });
19
+ const recipientSchema = zod_1.z
20
+ .union([zod_1.z.string().email(), zod_1.z.array(zod_1.z.string().email()).min(1)])
21
+ .transform((v) => (Array.isArray(v) ? v : [v]));
22
+ server.registerTool("send_email", {
23
+ description: "Send an email via SMTP. Recipient addresses are validated against the server's allowed domains/addresses policy.",
24
+ inputSchema: {
25
+ to: recipientSchema.describe("Recipient address or list of addresses"),
26
+ subject: zod_1.z.string().min(1).describe("Email subject line"),
27
+ body: zod_1.z.string().min(1).describe("Email body content"),
28
+ body_type: zod_1.z
29
+ .enum(["text", "html"])
30
+ .default("text")
31
+ .describe("Body format — plain text (default) or HTML"),
32
+ cc: recipientSchema
33
+ .optional()
34
+ .describe("CC address or list of addresses"),
35
+ bcc: recipientSchema
36
+ .optional()
37
+ .describe("BCC address or list of addresses"),
38
+ attachments: zod_1.z
39
+ .array(attachmentSchema)
40
+ .optional()
41
+ .describe("Files to attach"),
42
+ },
43
+ }, async (args) => {
44
+ const allRecipients = [
45
+ ...args.to,
46
+ ...(args.cc ?? []),
47
+ ...(args.bcc ?? []),
48
+ ];
49
+ const check = (0, restrictions_js_1.checkRecipients)(allRecipients, config_js_1.config.restrictions);
50
+ if (!check.allowed) {
51
+ return {
52
+ isError: true,
53
+ content: [
54
+ {
55
+ type: "text",
56
+ text: `Recipient(s) not permitted by server policy: ${check.blocked.join(", ")}`,
57
+ },
58
+ ],
59
+ };
60
+ }
61
+ try {
62
+ const result = await (0, email_js_1.sendEmail)(transport, config_js_1.config.from, {
63
+ to: args.to,
64
+ subject: args.subject,
65
+ body: args.body,
66
+ body_type: args.body_type,
67
+ cc: args.cc,
68
+ bcc: args.bcc,
69
+ attachments: args.attachments,
70
+ });
71
+ return {
72
+ content: [
73
+ {
74
+ type: "text",
75
+ text: `Email sent successfully. Message ID: ${result.messageId}`,
76
+ },
77
+ ],
78
+ };
79
+ }
80
+ catch (err) {
81
+ const message = err instanceof Error ? err.message : String(err);
82
+ return {
83
+ isError: true,
84
+ content: [{ type: "text", text: `Failed to send email: ${message}` }],
85
+ };
86
+ }
87
+ });
88
+ async function main() {
89
+ const stdio = new stdio_js_1.StdioServerTransport();
90
+ await server.connect(stdio);
91
+ console.error("SMTP MCP server running on stdio");
92
+ }
93
+ main().catch((err) => {
94
+ console.error("Fatal error:", err);
95
+ process.exit(1);
96
+ });
@@ -0,0 +1,27 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.checkRecipients = checkRecipients;
4
+ function domainOf(address) {
5
+ return address.split("@")[1]?.toLowerCase() ?? "";
6
+ }
7
+ function checkRecipients(addresses, restrictions) {
8
+ const { allowedDomains, allowedAddresses } = restrictions;
9
+ // No restrictions configured — permit everything.
10
+ if (allowedDomains.length === 0 && allowedAddresses.length === 0) {
11
+ return { allowed: true };
12
+ }
13
+ const normalizedAllowedAddresses = allowedAddresses.map((a) => a.toLowerCase());
14
+ const normalizedAllowedDomains = allowedDomains.map((d) => d.toLowerCase());
15
+ const blocked = addresses.filter((addr) => {
16
+ const lower = addr.toLowerCase();
17
+ if (normalizedAllowedAddresses.includes(lower))
18
+ return false;
19
+ if (normalizedAllowedDomains.includes(domainOf(lower)))
20
+ return false;
21
+ return true;
22
+ });
23
+ if (blocked.length > 0) {
24
+ return { allowed: false, blocked };
25
+ }
26
+ return { allowed: true };
27
+ }
package/package.json ADDED
@@ -0,0 +1,47 @@
1
+ {
2
+ "name": "@teamnetwork-nz/smtp-mcp-server",
3
+ "version": "1.0.0",
4
+ "description": "MCP server for sending email via SMTP relay",
5
+ "main": "dist/index.js",
6
+ "bin": {
7
+ "smtp-mcp-server": "dist/index.js"
8
+ },
9
+ "files": [
10
+ "dist",
11
+ "README.md",
12
+ ".env.example"
13
+ ],
14
+ "scripts": {
15
+ "build": "tsc",
16
+ "start": "node dist/index.js",
17
+ "dev": "tsc --watch",
18
+ "prepublishOnly": "npm run build"
19
+ },
20
+ "keywords": [
21
+ "mcp",
22
+ "smtp",
23
+ "email",
24
+ "model-context-protocol",
25
+ "claude"
26
+ ],
27
+ "author": "",
28
+ "license": "ISC",
29
+ "type": "commonjs",
30
+ "engines": {
31
+ "node": ">=18.0.0"
32
+ },
33
+ "publishConfig": {
34
+ "access": "public"
35
+ },
36
+ "dependencies": {
37
+ "@modelcontextprotocol/sdk": "^1.29.0",
38
+ "dotenv": "^17.4.2",
39
+ "nodemailer": "^8.0.7",
40
+ "zod": "^4.4.3"
41
+ },
42
+ "devDependencies": {
43
+ "@types/node": "^25.7.0",
44
+ "@types/nodemailer": "^8.0.0",
45
+ "typescript": "^6.0.3"
46
+ }
47
+ }