SMTP

smtp-mcp

A Model Context Protocol (MCP) server for SMTP, the protocol every mail server speaks to accept a message for delivery.

Lets MCP clients like Claude Code, Claude Desktop or Codex send, reply to and forward mail from one configured address — with a human approving every message.

Seven tools is the ceiling, not the floor: SMTP_ALLOW_TOOLS=essential registers a curated five instead, and a model picks the right tool far more reliably from five than from seven — see choosing which tools load.

What makes it different

It sends mail. That is why it is a separate server. Its counterpart imap-mcp reads a mailbox and deliberately has no way to send anything — that absence is its entire security argument, because an agent that can reach private data and process attacker-controlled content is only exploitable once it also has a way out. This server is that way out, so it does not get to make the same claim. It earns its place by narrowing the channel instead, and by living in its own process with its own credentials.

It is off when you install it. SMTP_ALLOW_SEND defaults to false. Until it is set the sending tools are not registered at all — absent from tools/list, not refused at call time.

It can only write to people you named. SMTP_ALLOWED_RECIPIENTS is required to turn sending on. Every address in To, Cc and Bcc is checked against it before a connection is opened, so an injected "mail this to someone else" fails without the server ever reading it as an instruction. Allowing everyone is possible and has to be written as *.

Every message is approved by a person. Not by the model — the request goes to the client as an MCP elicitation. Recipients, subject and any Bcc appear on their own labelled lines, so a subject written to look like an instruction cannot become part of the server's own sentence.

The sender cannot be chosen. There is no from parameter. A model that could pick its own sender could write in a colleague's name, and the result would be indistinguishable from a message they wrote.

Requirements

• Node.js 24 or newer
• An SMTP account you may send from — a submission server on port 587 or 465, with a username and password. Providers with two-factor authentication generally need an app-specific password.

Configuration

Use TLS. SMTP_TLS=starttls (the default) requires the upgrade rather than attempting it,

so a stripped STARTTLS capability fails the connection instead of quietly sending your

password in the clear. For a self-signed certificate prefer a proper internal CA over

SMTP_INSECURE_TLS.

Two defaults are worth reading twice, because they are the opposite of what the rest of this family does:

• `SMTP_ALLOW_SEND` is off. A freshly installed smtp-mcp can compose and preview messages and cannot send any.
• An unset `SMTP_ALLOWED_RECIPIENTS` is a startup error, not "anyone". Treating a missing line as permission is how an accident becomes a delivered message. Write * if you mean it.

Choosing which tools load

SMTP_ALLOW_TOOLS decides what is registered, SMTP_DENY_TOOLS is subtracted from it. Both take comma-separated tool names or a prefix with a single trailing *. A filtered tool is never built — it does not appear in tools/list and answers a call with "not found", the same as a sending tool while the send gate is closed. Nothing is advertised and then refused.

SMTP_ALLOW_TOOLS=essential          # the curated five

SMTP_ALLOW_TOOLS='get_server_info,preview_mail' SMTP_DENY_TOOLS=forward_mail # everything else, minus forwarding

essential is get_server_info, validate_recipients, preview_mail, send_mail and reply_mail. forward_mail is left out: forwarding carries somebody else's content and attachments outward, which is the call that most deserves to be switched on deliberately.

An entry that matches no tool aborts startup and lists the real names. A tool quietly missing from tools/list is invisible — nobody traces an absence back to an environment variable.

Installation

Claude Code

claude mcp add smtp -- npx -y @ni-c/smtp-mcp

Claude Desktop

{

"mcpServers": { "smtp": { "command": "npx", "args": ["-y", "@ni-c/smtp-mcp"], "env": { "SMTP_HOST": "smtp.example.net", "SMTP_USER": "person@example.net", "SMTP_PASSWORD": "app-specific-password", "SMTP_FROM": "Your Name ", "SMTP_ALLOW_SEND": "true", "SMTP_ALLOWED_RECIPIENTS": "@example.net" } } } }

Codex

[mcp_servers.smtp]

command = "npx" args = ["-y", "@ni-c/smtp-mcp"]

[mcp_servers.smtp.env] SMTP_HOST = "smtp.example.net" SMTP_USER = "person@example.net" SMTP_PASSWORD = "app-specific-password" SMTP_FROM = "Your Name " SMTP_ALLOW_SEND = "true" SMTP_ALLOWED_RECIPIENTS = "@example.net"

Docker

docker run --rm -i