Stalwart Mail MCP Server

Stalwart Mail MCP

Česky

An MCP server that lets Claude Desktop (or any MCP client that speaks stdio) work with a mailbox on your own Stalwart mail server: search and read mail including attachments and scans, reply in a thread, send, keep drafts, and look up or add contacts.

It talks JMAP with the mailbox's own credentials. Nothing is installed on the server.

Claude Desktop ──stdio──▶ dist/index.cjs (Node, this MCP server)
                              │  HTTPS · JMAP (RFC 8620 / 8621 / 9610)
                              ▼
                 https://mail.example.com/jmap   (reverse proxy → Stalwart)

There is also a remote mode: the same server run next to Stalwart, added to Claude as a custom connector, so the mailbox works in claude.ai, the mobile apps and every desktop chat — people sign in through Stalwart's own OAuth and the server holds no credentials. See docs/remote.md.

How it fits into a small self-hosted setup — reverse proxy, what to expose, shared mailboxes, branded builds for a family or a team — is described in docs/small-infrastructure.md.

Tools

Names carry a prefix, mail_ by default (a branded build can change it).

Sending is immediate and cannot be undone, so the tool descriptions tell the model to send only on the user's explicit instruction and to create a draft otherwise.

Install

Claude Desktop (extension)

Download stalwart-mail.mcpb from the latest release and open it — Claude Desktop offers to install it. Or build it yourself:

npm install
./pack.sh                  # → stalwart-mail.mcpb
open stalwart-mail.mcpb    # Claude Desktop → Install

Fill in the server address, the mailbox e-mail and password. Optional: the language and a Mistral API key for OCR. The password is kept in the operating system's keychain.

Any MCP client (stdio)

The server is on npm as stalwart-mail-mcp and in the MCP Registry as io.github.cybersmurf/stalwart-mail-mcp, so no checkout is needed:

{
  "mcpServers": {
    "stalwart-mail": {
      "command": "npx",
      "args": ["-y", "stalwart-mail-mcp"],
      "env": {
        "STALWART_URL": "https://mail.example.com",
        "STALWART_USER": "jane@example.com",
        "STALWART_PASSWORD": "…"
      }
    }
  }
}

Claude Code: claude mcp add stalwart-mail --env STALWART_URL=https://mail.example.com --env STALWART_USER=jane@example.com --env STALWART_PASSWORD=… -- npx -y stalwart-mail-mcp

Claude on the web, desktop chat and phone

Run the server next to Stalwart (stalwart-mail-mcp --http, or the Docker image) and add its URL as a custom connector — step by step in docs/remote.md.

Configuration

What it is allowed to do

Every capability is a switch in the extension settings (or an env variable above), all on by default. A capability that is off is not offered as a tool at all, so it holds regardless of what the client's approval prompts remember:

• sending off → a mailbox Claude can read and draft in, but never send from;
• sending, drafts and contact edits off → a read-only mailbox;
• saving attachments off → get_attachment reads the file from a temporary copy and is annotated read-only; with saving on it writes to the download folder and is annotated as a writing tool, which clients may treat differently when asking for approval.

Approvals themselves ("allow once / always allow") belong to the client, not to this server. In Claude Desktop they are set per tool in the extension's settings; a client may ask again after an update that changes a tool's definition.

Attachments and OCR

mail_get_attachment downloads the file and returns what the model can read:

• text files as text, HTML converted to text;
• PDFs as text page by page (page_from / page_to for long ones);
• PDF pages without a text layer (scans) and photos go to the OCR provider you choose — the result is markdown including tables, and those pages are marked (OCR). A mixed PDF sends only its scanned pages;
• images are returned as images; anything above ~600 kB or in HEIC is downscaled on macOS (sips);
• other types (docx, xlsx, zip…) are only saved, and the path is returned.

Without a provider, or with ocr: false, a scan comes back as an image of page 1 (macOS) with a note. OCR is the only thing in this server that sends content anywhere besides your mail server — to the provider you picked, or nowhere at all with a local model.

OCR providers

MAIL_OCR_API_KEY, MAIL_OCR_MODEL and MAIL_OCR_BASE_URL complete the choice. Examples:

MAIL_OCR_PROVIDER=ollama      MAIL_OCR_MODEL=llama3.2-vision                         # fully local
MAIL_OCR_PROVIDER=openrouter  MAIL_OCR_API_KEY=…  MAIL_OCR_MODEL=<a vision model>
MAIL_OCR_PROVIDER=anthropic   MAIL_OCR_API_KEY=…
MAIL_OCR_PROVIDER=custom      MAIL_OCR_BASE_URL=http://nas.lan:8000/v1  MAIL_OCR_MODEL=…

Providers that take images only get each scanned page as a PNG taken out of the PDF (the scan itself, scaled to 2000 px). A page that is not one big picture cannot be handed to them and is reported as unread; Mistral and Anthropic read any PDF. Pages are sent three at a time.

Things to expect: a local model can need a minute or more per dense page, which may exceed your client's tool timeout — read long scans in page ranges. General vision models transcribe well but, like every OCR, can misplace cells in tables with graphics; preview: true adds the page image so the model can check. With anthropic, a declined request is retried server-side on a fallback model (fallbacks: "default") on the current Claude models.

node test/live-ocr.mjs runs the provider configured in the environment against a scanned fixture (or your own file) and prints the result.

Languages

Tool titles, descriptions, output and error messages are localized. English is the source, Czech is written by hand, and German, Spanish, French, Italian, Dutch, Polish, Portuguese and Slovak are machine translations that no native speaker has reviewed yet — corrections are welcome.

To add or fix a language edit src/locales/<code>.ts (copy en.ts, keep the {placeholders} and line breaks) and register it in src/locales/index.ts. A locale may be partial; missing keys fall back to English. npm run test:offline checks every locale against the English keys.

Branded builds (presets)

For a family or a team you can ship an extension where the server address is pre-filled and people only type their e-mail and password. A preset is a folder with its own manifest.json (and optionally icon.png); see presets/example.

./pack.sh --preset /path/to/preset     # → /path/to/preset/<name>.mcpb

The preset's manifest sets MAIL_TOOL_PREFIX, MAIL_BRAND, MAIL_LANG or MAIL_DOWNLOAD_DIR through env, and gives server_url a default. Keep the preset's name stable so Claude Desktop treats new builds as updates.

Tests

npm run test:offline       # no mailbox needed: fake JMAP + fake OCR, the real server over stdio
MISTRAL_API_KEY=… node test/offline.mjs --live-ocr    # also sends the fixtures to the real OCR
STALWART_URL=… STALWART_USER=… STALWART_PASSWORD=… node test/smoke.mjs          # real mailbox
STALWART_URL=… STALWART_USER=… STALWART_PASSWORD=… node test/smoke.mjs --send   # also sends a mail to yourself

The offline test covers attachments, OCR, the tool prefix, language selection and locale consistency. The smoke test creates a draft and deletes it; with --send it leaves one test message in the mailbox.

Good to know

• A wrong password gets the IP banned by Stalwart after a few attempts. The server signs in on the first tool call, not at start, so restarting the client does not cause bans; calling tools repeatedly with a wrong password does.
• Built for and used with Stalwart 0.16. The mail part is plain RFC 8620/8621 and may work with other JMAP servers, but that is untested; contacts need JMAP for Contacts (RFC 9610).
• Email/query with "inMailbox": null is rejected by Stalwart — the filter must be absent or carry an id.
• The extension bundle is one CommonJS file (~3.8 MB, most of it pdf.js from unpdf); the .cjs extension matters because package.json says "type": "module".
• A tool result in Claude Desktop is capped at about 1 MB, hence the 600 kB limit for inline images.

License

MIT