stalwart-jmap-mcp

Unofficial MCP server for Stalwart Mail Server — talks to the JMAP management API (/jmap, Stalwart v1.0+).

⚠️ Stalwart 0.16+ removed the legacy REST management API in favor of JMAP. Most existing "stalwart MCP" projects target the old REST API and won't work on modern Stalwart. This server uses the x:-prefixed JMAP management methods directly.

Features (v0.4 — 39 tools, verified live on Stalwart v1.0.0)

Mail surface (v0.4 — standard JMAP mail)

Tool	Description
stalwart_list_mailboxes	Folders + email counts (inbox/trash/junk/sent/...)
stalwart_search_emails	Search by mailbox role + free text (from/to/subject/body)
stalwart_get_email	Full email: headers, body, raw blob
stalwart_list_identities	Sending identities (From addresses)
stalwart_get_vacation_response	Auto-reply settings
stalwart_list_sieve_scripts	Sieve filter scripts

⚠️ Admin token punya permission impersonate — parameter account_id bisa dipakai untuk membaca mailbox user lain. Gunakan dengan hati-hati.

Read (v0.1)

Tool	Description
stalwart_server_info	Edition, username, capabilities
stalwart_list_accounts	Mail accounts (users) with email/domain/created
stalwart_get_account	Full account detail by id or email (secrets masked)
stalwart_list_domains	Configured mail domains
stalwart_list_principals	Users/groups/lists/domains/roles/tenants
stalwart_list_dkim_signatures	DKIM keys: selector, stage, algorithm
stalwart_list_queue	Outgoing mail queue
stalwart_list_api_keys	API keys (masked)
stalwart_list_objects	Generic listing: tasks, alerts, roles, mailing lists, tenants, certificates, cluster nodes, applications, webhooks, tracers, ACME providers, DNS servers, spam rules, blocked/allowed IPs

Write (v0.2)

Tool	Description
stalwart_create_account	Create mail account (user)
stalwart_delete_account	Delete account (requires confirm)
stalwart_set_account_password	Reset account password
stalwart_create_domain	Add mail domain
stalwart_delete_domain	Delete domain (requires confirm)
stalwart_generate_dkim	Generate DKIM key (RSA 2048 / Ed25519)
stalwart_create_api_key	Create API key (token shown once)
stalwart_delete_api_key	Delete API key (requires confirm)
stalwart_reschedule_queue_message	Set next retry time of a queued message
stalwart_delete_queue_message	Delete message from queue (requires confirm)
stalwart_block_ip / stalwart_unblock_ip	Block / unblock IP (reason enum: rcptToFailure, authFailure, loitering, portScanning, manual, other)
stalwart_allow_ip / stalwart_unallow_ip	Allowlist / remove IP from allowlist
stalwart_create_mailing_list	Create mailing list (name + domain)
stalwart_delete_mailing_list	Delete mailing list (requires confirm)

Admin (v0.3)

Tool	Description
stalwart_reload_settings	Hot-reload server settings
stalwart_reload_tls_certificates	Reload TLS certificates
stalwart_queue_pause / stalwart_queue_resume	Pause/resume MTA queue
stalwart_invalidate_caches	Invalidate (all
stalwart_troubleshoot_dmarc	Live SPF/DKIM/ARC/DMARC troubleshoot
stalwart_classify_spam	Spam score + tags for a message

Install

# local development
git clone https://github.com/fredogemilang/stalwart-jmap-mcp
cd stalwart-jmap-mcp && uv sync

# or via uvx (PEP 503 index hosted on GitHub Pages)
uvx --extra-index-url https://<user>.github.io/stalwart-jmap-mcp/simple stalwart-jmap-mcp

Configure

export STALWART_URL=https://mail.example.com
export STALWART_TOKEN=API_xxxx

Get an API token from the Stalwart web admin (mail.example.com/login) → API keys.

Claude Code

Option A — uvx (install langsung dari GitHub Pages index)

Tambah ke .mcp.json di project root (atau claude mcp add):

{
  "mcpServers": {
    "stalwart": {
      "command": "uvx",
      "args": ["--refresh", "--extra-index-url", "https://fredogemilang.github.io/stalwart-jmap-mcp/simple", "stalwart-jmap-mcp"],
      "env": {
        "STALWART_URL": "https://mail.example.com",
        "STALWART_TOKEN": "your-api-key"
      }
    }
  }
}

Option B — local development

claude mcp add stalwart --env STALWART_URL=https://mail.example.com \
  --env STALWART_TOKEN=API_xxxx -- uv --directory /path/to/stalwart-jmap-mcp \
  run stalwart-jmap-mcp

Development

uv run python scripts/smoke_test.py   # end-to-end test via stdio

License

MIT