@teamnetwork-nz/smtp-mcp-server 1.0.0 → 1.1.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/README.md +38 -7
- package/dist/email.js +4 -0
- package/dist/index.js +144 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @teamnetwork-nz/smtp-mcp-server
|
|
2
2
|
|
|
3
|
-
An MCP server that lets AI agents send email via any SMTP relay. Recipient restrictions are enforced server-side — an agent cannot
|
|
3
|
+
An MCP server that lets AI agents send email via any SMTP relay. Recipient restrictions, sender identity, and SMTP credentials are all enforced server-side — an agent cannot override them.
|
|
4
4
|
|
|
5
5
|
## Features
|
|
6
6
|
|
|
@@ -10,6 +10,8 @@ An MCP server that lets AI agents send email via any SMTP relay. Recipient restr
|
|
|
10
10
|
- Restrict recipients to allowed domains and/or explicit addresses
|
|
11
11
|
- Configurable sender name and address
|
|
12
12
|
- Works with any SMTP server (Gmail, SendGrid, Mailgun, self-hosted, unauthenticated relay, etc.)
|
|
13
|
+
- `health` tool for live connection testing
|
|
14
|
+
- Built-in usage resource agents can read to understand available options
|
|
13
15
|
|
|
14
16
|
## Install
|
|
15
17
|
|
|
@@ -17,7 +19,7 @@ An MCP server that lets AI agents send email via any SMTP relay. Recipient restr
|
|
|
17
19
|
npm install -g @teamnetwork-nz/smtp-mcp-server
|
|
18
20
|
```
|
|
19
21
|
|
|
20
|
-
Or run directly with npx (no install needed):
|
|
22
|
+
Or run directly with npx (no global install needed):
|
|
21
23
|
|
|
22
24
|
```bash
|
|
23
25
|
npx @teamnetwork-nz/smtp-mcp-server
|
|
@@ -39,7 +41,7 @@ All configuration is via environment variables (loaded from `.env` if present).
|
|
|
39
41
|
|---|---|---|
|
|
40
42
|
| `SMTP_HOST` | yes | SMTP relay hostname |
|
|
41
43
|
| `SMTP_PORT` | no | Port — default `587` |
|
|
42
|
-
| `SMTP_SECURE` | no | `"true"` for port 465 implicit TLS;
|
|
44
|
+
| `SMTP_SECURE` | no | `"true"` for port 465 implicit TLS; otherwise STARTTLS |
|
|
43
45
|
| `SMTP_USER` | no | SMTP auth username — omit for unauthenticated relays |
|
|
44
46
|
| `SMTP_PASS` | no | SMTP auth password — omit for unauthenticated relays |
|
|
45
47
|
| `SMTP_FROM_ADDRESS` | yes | Envelope From address |
|
|
@@ -47,7 +49,7 @@ All configuration is via environment variables (loaded from `.env` if present).
|
|
|
47
49
|
| `ALLOWED_DOMAINS` | no | Comma-separated domains, e.g. `acme.com,partner.org` |
|
|
48
50
|
| `ALLOWED_ADDRESSES` | no | Comma-separated explicit addresses |
|
|
49
51
|
|
|
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
|
|
52
|
+
**Restriction logic:** a recipient is permitted if its domain matches `ALLOWED_DOMAINS` **or** it appears in `ALLOWED_ADDRESSES`. All addresses across `to`, `cc`, and `bcc` are checked — a single blocked address rejects the whole request. If neither variable is set, all addresses are permitted (not recommended for production).
|
|
51
53
|
|
|
52
54
|
## Claude Code Integration
|
|
53
55
|
|
|
@@ -75,7 +77,28 @@ Add to your `.claude/mcp_config.json` (or `claude_desktop_config.json`):
|
|
|
75
77
|
|
|
76
78
|
For an unauthenticated internal relay, omit `SMTP_USER` and `SMTP_PASS`.
|
|
77
79
|
|
|
78
|
-
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## Tools
|
|
83
|
+
|
|
84
|
+
### `health`
|
|
85
|
+
|
|
86
|
+
No parameters. Performs a live TCP+SMTP handshake against the configured server and returns the active configuration summary.
|
|
87
|
+
|
|
88
|
+
```
|
|
89
|
+
connection: OK (42 ms)
|
|
90
|
+
smtp_host: smtp.example.com:587
|
|
91
|
+
tls: STARTTLS
|
|
92
|
+
auth: authenticated as user@example.com
|
|
93
|
+
from: "My Agent" <agent@example.com>
|
|
94
|
+
restrictions: domains: example.com
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Returns `isError: true` if the connection test fails, with the SMTP error message included.
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
### `send_email`
|
|
79
102
|
|
|
80
103
|
| Parameter | Type | Required | Description |
|
|
81
104
|
|---|---|---|---|
|
|
@@ -95,9 +118,17 @@ For an unauthenticated internal relay, omit `SMTP_USER` and `SMTP_PASS`.
|
|
|
95
118
|
| `content` | string | Base64-encoded file data |
|
|
96
119
|
| `content_type` | string | MIME type, e.g. `application/pdf` |
|
|
97
120
|
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## Resource: `smtp://server/usage`
|
|
124
|
+
|
|
125
|
+
A plain-text usage guide populated with the server's live configuration (sender identity, SMTP endpoint, active restrictions, full tool reference). Agents can read this resource to understand what options are available without calling any tools.
|
|
126
|
+
|
|
127
|
+
---
|
|
128
|
+
|
|
98
129
|
## Local Testing with Mailpit
|
|
99
130
|
|
|
100
|
-
[Mailpit](https://mailpit.axllent.org/) is a lightweight local SMTP catcher:
|
|
131
|
+
[Mailpit](https://mailpit.axllent.org/) is a lightweight local SMTP catcher — no credentials required:
|
|
101
132
|
|
|
102
133
|
```bash
|
|
103
134
|
# macOS
|
|
@@ -107,4 +138,4 @@ brew install mailpit && mailpit
|
|
|
107
138
|
scoop install mailpit && mailpit
|
|
108
139
|
```
|
|
109
140
|
|
|
110
|
-
|
|
141
|
+
Set `SMTP_HOST=localhost`, `SMTP_PORT=1025`, omit `SMTP_USER`/`SMTP_PASS`. View caught emails at http://localhost:8025.
|
package/dist/email.js
CHANGED
|
@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
|
4
4
|
};
|
|
5
5
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
6
6
|
exports.createTransport = createTransport;
|
|
7
|
+
exports.verifyTransport = verifyTransport;
|
|
7
8
|
exports.sendEmail = sendEmail;
|
|
8
9
|
const nodemailer_1 = __importDefault(require("nodemailer"));
|
|
9
10
|
function createTransport(smtpConfig) {
|
|
@@ -16,6 +17,9 @@ function createTransport(smtpConfig) {
|
|
|
16
17
|
: {}),
|
|
17
18
|
});
|
|
18
19
|
}
|
|
20
|
+
async function verifyTransport(transport) {
|
|
21
|
+
await transport.verify();
|
|
22
|
+
}
|
|
19
23
|
async function sendEmail(transport, from, options) {
|
|
20
24
|
const message = {
|
|
21
25
|
from: `"${from.name}" <${from.address}>`,
|
package/dist/index.js
CHANGED
|
@@ -9,8 +9,11 @@ const email_js_1 = require("./email.js");
|
|
|
9
9
|
const transport = (0, email_js_1.createTransport)(config_js_1.config.smtp);
|
|
10
10
|
const server = new mcp_js_1.McpServer({
|
|
11
11
|
name: "smtp-mcp",
|
|
12
|
-
version: "1.
|
|
12
|
+
version: "1.1.0",
|
|
13
13
|
});
|
|
14
|
+
// ---------------------------------------------------------------------------
|
|
15
|
+
// Shared schemas
|
|
16
|
+
// ---------------------------------------------------------------------------
|
|
14
17
|
const attachmentSchema = zod_1.z.object({
|
|
15
18
|
filename: zod_1.z.string().min(1),
|
|
16
19
|
content: zod_1.z.string().min(1).describe("Base64-encoded file content"),
|
|
@@ -19,6 +22,54 @@ const attachmentSchema = zod_1.z.object({
|
|
|
19
22
|
const recipientSchema = zod_1.z
|
|
20
23
|
.union([zod_1.z.string().email(), zod_1.z.array(zod_1.z.string().email()).min(1)])
|
|
21
24
|
.transform((v) => (Array.isArray(v) ? v : [v]));
|
|
25
|
+
// ---------------------------------------------------------------------------
|
|
26
|
+
// Tool: health
|
|
27
|
+
// ---------------------------------------------------------------------------
|
|
28
|
+
server.registerTool("health", {
|
|
29
|
+
description: "Check that the SMTP server is reachable and the configuration is valid. " +
|
|
30
|
+
"Returns the active settings (host, port, auth mode, sender identity, restrictions) " +
|
|
31
|
+
"and the result of a live connection test.",
|
|
32
|
+
}, async () => {
|
|
33
|
+
const start = Date.now();
|
|
34
|
+
let connectionStatus;
|
|
35
|
+
let isError = false;
|
|
36
|
+
try {
|
|
37
|
+
await (0, email_js_1.verifyTransport)(transport);
|
|
38
|
+
connectionStatus = `OK (${Date.now() - start} ms)`;
|
|
39
|
+
}
|
|
40
|
+
catch (err) {
|
|
41
|
+
connectionStatus = `FAILED — ${err instanceof Error ? err.message : String(err)}`;
|
|
42
|
+
isError = true;
|
|
43
|
+
}
|
|
44
|
+
const { allowedDomains, allowedAddresses } = config_js_1.config.restrictions;
|
|
45
|
+
const restrictionSummary = allowedDomains.length === 0 && allowedAddresses.length === 0
|
|
46
|
+
? "none (all addresses permitted)"
|
|
47
|
+
: [
|
|
48
|
+
allowedDomains.length
|
|
49
|
+
? `domains: ${allowedDomains.join(", ")}`
|
|
50
|
+
: null,
|
|
51
|
+
allowedAddresses.length
|
|
52
|
+
? `addresses: ${allowedAddresses.join(", ")}`
|
|
53
|
+
: null,
|
|
54
|
+
]
|
|
55
|
+
.filter(Boolean)
|
|
56
|
+
.join(" | ");
|
|
57
|
+
const lines = [
|
|
58
|
+
`connection: ${connectionStatus}`,
|
|
59
|
+
`smtp_host: ${config_js_1.config.smtp.host}:${config_js_1.config.smtp.port}`,
|
|
60
|
+
`tls: ${config_js_1.config.smtp.secure ? "implicit (port 465)" : "STARTTLS"}`,
|
|
61
|
+
`auth: ${config_js_1.config.smtp.user ? `authenticated as ${config_js_1.config.smtp.user}` : "unauthenticated"}`,
|
|
62
|
+
`from: "${config_js_1.config.from.name}" <${config_js_1.config.from.address}>`,
|
|
63
|
+
`restrictions: ${restrictionSummary}`,
|
|
64
|
+
];
|
|
65
|
+
return {
|
|
66
|
+
isError,
|
|
67
|
+
content: [{ type: "text", text: lines.join("\n") }],
|
|
68
|
+
};
|
|
69
|
+
});
|
|
70
|
+
// ---------------------------------------------------------------------------
|
|
71
|
+
// Tool: send_email
|
|
72
|
+
// ---------------------------------------------------------------------------
|
|
22
73
|
server.registerTool("send_email", {
|
|
23
74
|
description: "Send an email via SMTP. Recipient addresses are validated against the server's allowed domains/addresses policy.",
|
|
24
75
|
inputSchema: {
|
|
@@ -85,6 +136,98 @@ server.registerTool("send_email", {
|
|
|
85
136
|
};
|
|
86
137
|
}
|
|
87
138
|
});
|
|
139
|
+
// ---------------------------------------------------------------------------
|
|
140
|
+
// Resource: usage guide for agents
|
|
141
|
+
// ---------------------------------------------------------------------------
|
|
142
|
+
function buildUsageText() {
|
|
143
|
+
const { allowedDomains, allowedAddresses } = config_js_1.config.restrictions;
|
|
144
|
+
const hasRestrictions = allowedDomains.length > 0 || allowedAddresses.length > 0;
|
|
145
|
+
const restrictionSection = hasRestrictions
|
|
146
|
+
? [
|
|
147
|
+
"RECIPIENT RESTRICTIONS",
|
|
148
|
+
"An address is permitted when it satisfies at least one rule:",
|
|
149
|
+
allowedDomains.length
|
|
150
|
+
? ` Allowed domains: ${allowedDomains.join(", ")}`
|
|
151
|
+
: null,
|
|
152
|
+
allowedAddresses.length
|
|
153
|
+
? ` Allowed addresses: ${allowedAddresses.join(", ")}`
|
|
154
|
+
: null,
|
|
155
|
+
"Blocked addresses are rejected before any connection is made to the SMTP server.",
|
|
156
|
+
]
|
|
157
|
+
.filter((l) => l !== null)
|
|
158
|
+
.join("\n")
|
|
159
|
+
: "RECIPIENT RESTRICTIONS\nNone configured — all addresses are permitted.";
|
|
160
|
+
return `
|
|
161
|
+
SMTP MCP SERVER — USAGE GUIDE
|
|
162
|
+
==============================
|
|
163
|
+
|
|
164
|
+
This server sends email on behalf of agents via an SMTP relay.
|
|
165
|
+
All configuration (credentials, sender identity, restrictions) is fixed at
|
|
166
|
+
startup and cannot be changed by tool calls.
|
|
167
|
+
|
|
168
|
+
SENDER IDENTITY
|
|
169
|
+
From name: ${config_js_1.config.from.name}
|
|
170
|
+
From address: ${config_js_1.config.from.address}
|
|
171
|
+
|
|
172
|
+
SMTP ENDPOINT
|
|
173
|
+
Host: ${config_js_1.config.smtp.host}
|
|
174
|
+
Port: ${config_js_1.config.smtp.port}
|
|
175
|
+
TLS: ${config_js_1.config.smtp.secure ? "implicit (port 465)" : "STARTTLS"}
|
|
176
|
+
Auth: ${config_js_1.config.smtp.user ? "enabled" : "none"}
|
|
177
|
+
|
|
178
|
+
${restrictionSection}
|
|
179
|
+
|
|
180
|
+
TOOLS
|
|
181
|
+
-----
|
|
182
|
+
|
|
183
|
+
health
|
|
184
|
+
No parameters.
|
|
185
|
+
Performs a live TCP+SMTP connection test and returns the active configuration.
|
|
186
|
+
Call this first to confirm the server is reachable before sending.
|
|
187
|
+
|
|
188
|
+
send_email
|
|
189
|
+
Required
|
|
190
|
+
to string | string[] One or more recipient email addresses.
|
|
191
|
+
subject string Subject line.
|
|
192
|
+
body string Message body (plain text or HTML).
|
|
193
|
+
|
|
194
|
+
Optional
|
|
195
|
+
body_type "text" | "html" Default: "text". Use "html" for rich content.
|
|
196
|
+
cc string | string[] Carbon copy recipients.
|
|
197
|
+
bcc string | string[] Blind carbon copy recipients.
|
|
198
|
+
attachments Attachment[] Files to attach (see schema below).
|
|
199
|
+
|
|
200
|
+
Attachment schema
|
|
201
|
+
filename string Name shown to the recipient (e.g. "report.pdf").
|
|
202
|
+
content string File data encoded as base64.
|
|
203
|
+
content_type string MIME type (e.g. "application/pdf", "image/png").
|
|
204
|
+
|
|
205
|
+
TIPS
|
|
206
|
+
----
|
|
207
|
+
- Call health before send_email if you are unsure whether the relay is up.
|
|
208
|
+
- body_type defaults to plain text; only set "html" when you need formatting.
|
|
209
|
+
- All addresses in to, cc, and bcc are checked against restrictions — a single
|
|
210
|
+
blocked address will reject the entire request.
|
|
211
|
+
- Attachments have no size limit enforced by this server; the SMTP relay may
|
|
212
|
+
impose its own limits.
|
|
213
|
+
`.trim();
|
|
214
|
+
}
|
|
215
|
+
server.registerResource("usage", "smtp://server/usage", {
|
|
216
|
+
title: "SMTP MCP Server — Usage Guide",
|
|
217
|
+
description: "Reference guide describing this server's tools, parameters, active sender identity, and recipient restrictions.",
|
|
218
|
+
mimeType: "text/plain",
|
|
219
|
+
}, async () => ({
|
|
220
|
+
contents: [
|
|
221
|
+
{
|
|
222
|
+
uri: "smtp://server/usage",
|
|
223
|
+
text: buildUsageText(),
|
|
224
|
+
mimeType: "text/plain",
|
|
225
|
+
},
|
|
226
|
+
],
|
|
227
|
+
}));
|
|
228
|
+
// ---------------------------------------------------------------------------
|
|
229
|
+
// Start
|
|
230
|
+
// ---------------------------------------------------------------------------
|
|
88
231
|
async function main() {
|
|
89
232
|
const stdio = new stdio_js_1.StdioServerTransport();
|
|
90
233
|
await server.connect(stdio);
|