@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 +16 -0
- package/README.md +110 -0
- package/dist/config.js +70 -0
- package/dist/email.js +40 -0
- package/dist/index.js +96 -0
- package/dist/restrictions.js +27 -0
- package/package.json +47 -0
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
|
+
}
|