smtp-mcp

# smtp-mcp

<!-- badges: start -->

[![CI](https://img.shields.io/github/actions/workflow/status/ni-c/smtp-mcp/ci.yml?branch=main&label=CI)](https://github.com/ni-c/smtp-mcp/actions/workflows/ci.yml)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ni-c/smtp-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/ni-c/smtp-mcp)
<a href="https://socket.dev/npm/package/@ni-c/smtp-mcp"><img src="https://socket.dev/api/badge/npm/package/@ni-c/smtp-mcp" alt="Socket supply-chain report" height="20"></a>
[![Glama score](https://glama.ai/mcp/servers/ni-c/smtp-mcp/badges/score.svg)](https://glama.ai/mcp/servers/ni-c/smtp-mcp)
<br>
[![npm version](https://img.shields.io/npm/v/%40ni-c%2Fsmtp-mcp)](https://www.npmjs.com/package/@ni-c/smtp-mcp)
[![container image](https://img.shields.io/badge/ghcr.io-ni--c%2Fsmtp--mcp-4f46e5?logo=docker&logoColor=white)](https://github.com/ni-c/smtp-mcp/pkgs/container/smtp-mcp)
[![HTTP via mcp-hub](https://img.shields.io/badge/HTTP-via%20mcp--hub-4f46e5?logo=modelcontextprotocol&logoColor=white)](https://mcp-hub.ni-c.de)
<br>
[![docs](https://img.shields.io/badge/docs-smtp--mcp.ni--c.de-4f46e5?logo=readthedocs&logoColor=white)](https://smtp-mcp.ni-c.de)
[![sponsor](https://img.shields.io/badge/sponsor-ni--c-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/ni-c)
<!-- badges: end -->

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for
[SMTP](https://datatracker.ietf.org/doc/html/rfc5321), 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](#choosing-which-tools-load).

<!-- The <picture> element resolves against the page, so it follows GitHub's theme
     toggle. npm strips <picture> while sanitising and keeps the <img>, which is
     why architecture.svg carries its own dark card. URLs must be absolute:
     relative paths are simply invisible on the npm package page. -->
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://smtp-mcp.ni-c.de/architecture-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="https://smtp-mcp.ni-c.de/architecture-light.svg">
  <img src="https://smtp-mcp.ni-c.de/architecture.svg" alt="An MCP client talking to smtp-mcp over stdio, which checks every recipient against an allowlist and asks a person to approve the message before handing it to a submission server over TLS" width="800">
</picture>

<img src="https://smtp-mcp.ni-c.de/demo.gif" alt="Listing the seven tools, then calling send_mail — which sends nothing and comes back asking, with the recipient and subject on their own labelled lines — and then a second call to an address outside the allowlist, which is refused before any connection is opened" width="800">

## What makes it different

**It sends mail. That is why it is a separate server.** Its counterpart
[imap-mcp](https://github.com/ni-c/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_REPLY_TO`             | no                          | —                            | Reply-To on every message, e.g. `Team <team@example.net>`. Unset means replies go to `SMTP_FROM`. |
| `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".*