stalwart-mcp

An MCP server for Stalwart mail servers, built on JMAP. It lets Claude (or any MCP client) search, read, write and organise mail, manage folders, Sieve filters and out-of-office replies — with safety rules for the parts where an AI assistant can do damage.

It runs in two ways:

• As a sidecar behind an MCP hub (the T-0 MCP hub): the hub stores each person's Stalwart credential and sends it with every tool call. The hub manifests are generated into service.yaml (mail) and manifests/stalwart-admin/service.yaml (admin).

• Standalone next to your Stalwart server, added to Claude as a custom connector. (OAuth sign-in against Stalwart's own OAuth server is on the roadmap; see below.)

Tools

Every tool carries MCP annotations (readOnlyHint, destructiveHint, openWorldHint), so clients like claude.ai can ask for approval on writes.

Related MCP server: email-mcp

Admin tools (/admin/mcp)

A second MCP endpoint on the same server, for administrators, over Stalwart 0.16's JMAP management API (urn:stalwart:jmap; reference with all quirks: docs/stalwart-management-api.md). Credential: the administrator's own API key (Bearer API_…), ideally restricted to the server's IP.

Safety model

Mail is the one data source where anyone on the internet can put text in front of the model. The server assumes that this text may contain instructions (prompt injection) and limits what such text can achieve:

• Draft first. write_email never sends. send_email refuses unless confirm_recipients lists exactly the draft's recipients, so the approval dialog shows who will receive the mail. Bcc is passed at send time and never written into the stored message.

• No silent forwarding. save_filter refuses Sieve redirect/notify targets outside the account's own domains unless allow_external_redirect=true is passed explicitly.

• No outbound requests to internal networks. One-click unsubscribe only calls https URLs whose host resolves to public addresses, does not follow redirects and ignores the response body.

• Hidden HTML is dropped before the model sees a body (display:none, zero-size text, tracking pixels). This is damage control, not a boundary: every result with mail content is marked as untrusted data.

• Permanent deletion only for mails already in Trash or Junk; system folders cannot be renamed or deleted.

Operating against Stalwart

Rules learned against a production Stalwart (0.16), enforced in jmap.py:

• Rejected credentials are never retried. Stalwart bans the source IP after failed logins — on some setups after a single one — for every account behind that IP. A rejected credential is quarantined for an hour; a new credential passes immediately.

• One pacing budget per process (default 4 request starts/s, 4 concurrent). Stalwart counts per source IP, and behind a hub all users share one IP. Searches are batched into single JMAP requests with result references.

• Put this server's IP on Stalwart's allowed list (Settings › Security › Allowed IPs) and then run the action Reload Settings — allowed-IP entries only take effect after a reload. Allowed IPs bypass rate limits and automatic bans, so one person's typo cannot lock everyone out; the quarantine above replaces Stalwart's brute-force protection for that IP. Unblocking a banned IP likewise needs Reload Blocked IPs (manage_ip does both).

• Email/changes always runs in its own HTTP request: a stale state token answers HTTP 400 for the whole request.

• Email/set is always written as a patch (mailboxIds/<id>, keywords/<kw>); keywords are lowercase.

• The header condition of Email/query returns no results on Stalwart instead of an error, so it is not offered.

Configuration

Credentials arrive per request in the Authorization header: Bearer user@domain:app-password (what a hub sends; forwarded as HTTP Basic), Bearer <token> (Stalwart API key or OAuth token) or Basic ….

Endpoints: POST /mcp (MCP, Streamable HTTP, stateless), GET /health, GET /auth-check (one session request with the given credential — used by the hub's "test connection").

Running

docker run -p 8000:8000 -e STALWART_URL=https://mail.example.com ghcr.io/t-0-co/hub-service-stalwart:latest

Hub installation

The hub loads one service.yaml per repository, so there are two service repositories per hub:

Set STALWART_URL and STALWART_MCP_URL=http://stalwart-mcp:8000 for both. Give stalwart-admin only to the admin group. Hub >= 2.28.0 is needed for mcpProxy.passthrough (images and error flags reach the client unchanged).

Development

uv sync
uv run pytest -q                               # unit tests + tests against an in-process fake Stalwart (mail + admin)
uv run pytest -m live tests/test_live.py       # against a real throwaway mailbox, see the file header
uv run ruff check src scripts tests
uv run python scripts/gen_service_yaml.py      # regenerate both manifests after tool changes (CI checks it)
STALWART_URL=https://mail.example.com uv run stalwart-mcp

The hub registers proxied tools from service.yaml, not from the sidecar, so the manifest is generated from the server's own tool list and CI fails when they drift.

Roadmap

• Standalone OAuth: the server as an OAuth resource server delegating sign-in to Stalwart's built-in OAuth (dynamic client registration + PKCE), so it can be added to Claude as a custom connector without app passwords.