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 22 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.

Variable	Required	Default	Description
SMTP_HOST	yes	—	Hostname of the SMTP server, e.g. smtp.example.net.
SMTP_USER	yes	—	Username for SMTP authentication.
SMTP_PASSWORD	yes	—	Password or app-specific password.
SMTP_FROM	yes	—	The only sender used, e.g. Name <person@example.net>. There is no from parameter.
SMTP_PORT	no	587 / 465 / 25	Depends on SMTP_TLS.
SMTP_TLS	no	starttls	starttls, implicit or none. Never opportunistic.
SMTP_ALLOW_SEND	no	false	Set to true to register the sending tools.
SMTP_ALLOWED_RECIPIENTS	with SMTP_ALLOW_SEND=true	—	Comma-separated addresses and @domains. * allows anyone.
SMTP_MAX_RECIPIENTS	no	10	Distinct recipients across To, Cc and Bcc in one message.
SMTP_MAX_SENDS_PER_HOUR	no	20	Sliding hourly cap.
SMTP_MAX_MESSAGE_BYTES	no	10485760	Size ceiling on the composed message.
SMTP_MAX_ATTACHMENT_BYTES	no	5242880	Size ceiling on one attachment.
SMTP_ATTACHMENT_DIR	no	—	Directory attachments are read from. Unset means no attachments.
SMTP_ATTACHMENT_TYPES	no	document and image allowlist	Comma-separated content types that may be attached. text/html and application/zip are opt-in.
SMTP_SIGNATURE	no	—	Text appended below the standard -- delimiter.
SMTP_AUDIT_LOG	no	—	File the audit lines are appended to, in addition to stderr.
SMTP_ALLOW_TOOLS	no	—	Tool names, a prefix with one trailing *, or essential.
SMTP_DENY_TOOLS	no	—	Removed after SMTP_ALLOW_TOOLS is applied.
SMTP_INSECURE_TLS	no	false	Accept self-signed certificates.
ELICITATION	no	true	false replaces the approval dialog with the two-call token. Not prefixed.

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