mcp-server-stalwart

MCP server for Stalwart Mail Server. Provides email operations (search, read, send, delete) via JMAP and optional admin API access for server management.

Requirements

• Rust (2024 edition)
• A Stalwart mail server with JMAP enabled

Build

cargo build --release

Binary is output to `target/release/mcp-server-stalwart`.

Configuration

The server connects via stdio and is configured through environment variables.

Required

Optional (other mailboxes)

Switch tools onto another mailbox with `account` (e.g. `hello@codechap.com`) without needing the admin API.

Optional (admin API)

Password gotcha (learned the hard way)

If an app (invoice mailer, WordPress, etc.) is configured with the admin password as the SMTP secret, Stalwart returns `535 Authentication credentials invalid` and nothing is queued. `check_sent` will correctly show zero submissions. Use `verify_account_auth` to test credentials before chasing delivery.

Claude Code MCP config

{
  "mcpServers": {
    "stalwart": {
      "command": "/path/to/mcp-server-stalwart",
      "env": {
        "JMAP_SESSION_URL": "https://mail.example.com/jmap/session",
        "JMAP_USERNAME": "you@example.com",
        "JMAP_PASSWORD": "your-password",
        "JMAP_SECRETS_FILE": "/home/you/.local/share/mailman4/secrets.toml",
        "STALWART_ADMIN_URL": "https://mail.example.com",
        "STALWART_ADMIN_PASSWORD": "admin-password"
      }
    }
  }
}

Tools

get_mailboxes

List all mailboxes/folders with message counts.

create_mailbox

Create a new mailbox/folder.

search_emails

Search emails with filters. Returns email IDs -- use `get_emails` to read full content.

get_emails

Get full email content by IDs. Returns subject, from, to, date, body text, and metadata.

delete_emails

Permanently delete emails by ID. Cannot be undone.

send_email

Send an email with optional HTML body and file attachments. When `html_body` is provided, the email is sent as multipart with both plain text and HTML parts -- the recipient's email client will choose which to display.

Attachment object:

download_attachments

Download all attachments from an email to a local directory.

create_account (admin)

Create a new email account on the server. Requires admin API configuration.

list_accounts (admin)

List all accounts, or get details for one. Requires admin API configuration.

manage_aliases (admin)

Add or remove an email alias on an account. Requires admin API configuration.

update_account_permissions (admin)

Update an account's `enabledPermissions`. Newly-created principals start with no permissions and cannot authenticate, send, or receive mail until permissions are granted. Requires admin API configuration.

reset_password (admin)

Reset an account's password. If `password` is omitted, a strong 24-character random password is generated. The new password is returned in plaintext in the response so it can be delivered to the user. Requires admin API configuration.

get_dsn_accounts (admin)

List email addresses that have DSN (Delivery Status Notification) delivery reports enabled. Requires admin API configuration.

set_dsn_accounts (admin)

Set which email addresses receive DSN delivery reports (SUCCESS + FAILURE). Replaces the full list. Requires admin API configuration.

check_sent (admin)

The first tool to reach for when verifying any outbound email — contact forms, WordPress `wp_mail()`, invoice/statement mailers, password resets, transactional mail — anything needing *"did this leave the server?"*.

Reads Stalwart's `/api/logs` (authoritative) and groups by `queueId`: submission → delivery attempt → final status (`delivery.delivered` / `delivery.dsn-success` / `delivery.failed`) plus upstream MX `code`/`hostname`.

Do NOT search mailboxes first — SMTP submissions are not auto-saved to Sent. Start here.

How the log fetch works (production lesson):

Stalwart's server-side `filter=` query often hangs on multi-GB daily log files. By default this tool fetches the newest `scan_limit` rows unfiltered and applies `to`/`from`/`filter` client-side (fast: ~300ms for 1000 rows). Pass `use_server_filter=true` only if you know you need it (e.g. a unique queueId on a quiet host).

Common use cases:

• "Did the invoice mailer / contact form send to `ap@client.com`?"
• "Was a transactional email delivered — what did Gmail return?"
• "Why bounce — remote SMTP code?"

Returns `messages_found`, `delivered_count`, `failed_count`, per-message timelines (`mx_code` / `mx_hostname`), plus `auth_events` (submission auth success/failure) and a `log_window`.

verify_account_auth

Test whether a username/password is accepted by Stalwart (same secret as SMTP port 587). Use when `check_sent` shows no submission — usually the app has the wrong password.