{"id":"7dae4169-9d5a-4654-bbd4-8688a5f1ad88","slug":"stalwart-mail-mcp","kind":"mcp","name":"stalwart-mail-mcp","summary":"MCP server for a Stalwart mailbox over JMAP: search, read, attachments with OCR, send, drafts, contacts","owner":"cybersmurf","repoUrl":"https://github.com/cybersmurf/stalwart-mail-mcp","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-10-02T16:42:17.000Z","addedAt":"2026-10-14T05:32:42.207Z","logoUrl":"https://avatars.githubusercontent.com/u/3642214?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["files-documents","search","productivity"],"tags":["claude","email","jmap","ocr","stalwart"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":true,"reviewed":false,"syncedAt":"2026-10-14T15:20:28.756Z","sample":false,"url":"https://conduits.dev/tools/stalwart-mail-mcp","language":"TypeScript","transports":["stdio"],"install":{"npm":"stalwart-mail-mcp"},"requirements":{"env":[{"name":"STALWART_URL","secret":false,"required":true,"description":"Public address of the Stalwart server, e.g. https://mail.example.com"},{"name":"STALWART_USER","secret":false,"required":true,"description":"Mailbox e-mail address to sign in with"},{"name":"STALWART_PASSWORD","secret":true,"required":true,"description":"Mailbox or app password"},{"name":"MAIL_LANG","secret":false,"required":false,"description":"Language: auto, en, cs, de, es, fr, it, nl, pl, pt, sk"},{"name":"MAIL_OCR_PROVIDER","secret":false,"required":false,"description":"OCR of scans: auto, off, mistral, anthropic, openai, openrouter, gemini, ollama, lmstudio, custom"},{"name":"MAIL_OCR_API_KEY","secret":true,"required":false,"description":"API key of the OCR provider (not needed for local servers)"},{"name":"MAIL_OCR_MODEL","secret":false,"required":false,"description":"OCR model name"},{"name":"MAIL_OCR_BASE_URL","secret":false,"required":false,"description":"Address of a custom OpenAI-compatible OCR server"}],"upstreamMayCharge":false},"tools":null,"readme":"# Stalwart Mail MCP\n\n*[Česky](README.cs.md)*\n\nAn MCP server that lets Claude Desktop (or any MCP client that speaks stdio) work with a mailbox\non your own [Stalwart](https://stalw.art) mail server: search and read mail including\nattachments and scans, reply in a thread, send, keep drafts, and look up or add contacts.\n\nIt talks JMAP with the mailbox's own credentials. Nothing is installed on the server.\n\n```text\nClaude Desktop ──stdio──▶ dist/index.cjs (Node, this MCP server)\n                              │  HTTPS · JMAP (RFC 8620 / 8621 / 9610)\n                              ▼\n                 https://mail.example.com/jmap   (reverse proxy → Stalwart)\n```\n\nThere is also a **remote mode**: the same server run next to Stalwart, added to Claude as a\ncustom connector, so the mailbox works in claude.ai, the mobile apps and every desktop chat —\npeople sign in through Stalwart's own OAuth and the server holds no credentials. See\n[docs/remote.md](docs/remote.md).\n\nHow it fits into a small self-hosted setup — reverse proxy, what to expose, shared mailboxes,\nbranded builds for a family or a team — is described in\n[docs/small-infrastructure.md](docs/small-infrastructure.md).\n\n## Tools\n\nNames carry a prefix, `mail_` by default (a branded build can change it).\n\n| Tool | What it does |\n|---|---|\n| `mail_list_mailboxes` | accounts (own + shared), folders with counts, allowed senders, address books |\n| `mail_search_emails` | full text / from / to / subject / folder / date / unread / has attachment, or a whole thread |\n| `mail_get_email` | a whole message by id (HTML → text) with a numbered list of attachments |\n| `mail_get_attachment` | an attachment's content: text, PDF page by page, OCR of scans and photographed documents, images; saves the file to disk |\n| `mail_send_email` | send a new mail or a reply (`in_reply_to_id`, `reply_all`), attachments from disk |\n| `mail_create_draft` | the same, but only saved to Drafts |\n| `mail_send_draft` / `mail_delete_draft` | send / delete a draft by id |\n| `mail_search_contacts` | address books of every account plus senders and recipients from the mail history |\n| `mail_add_contact` | new contact (own or shared address book) |\n\nSending is immediate and cannot be undone, so the tool descriptions tell the model to send only\non the user's explicit instruction and to create a draft otherwise.\n\n## Install\n\n### Claude Desktop (extension)\n\nDownload `stalwart-mail.mcpb` from the\n[latest release](https://github.com/cybersmurf/stalwart-mail-mcp/releases/latest) and open it —\nClaude Desktop offers to install it. Or build it yourself:\n\n```bash\nnpm install\n./pack.sh                  # → stalwart-mail.mcpb\nopen stalwart-mail.mcpb    # Claude Desktop → Install\n```\n\nFill in the server address, the mailbox e-mail and password. Optional: the language and a\nMistral API key for OCR. The password is kept in the operating system's keychain.\n\n### Any MCP client (stdio)\n\nThe server is on npm as [`stalwart-mail-mcp`](https://www.npmjs.com/package/stalwart-mail-mcp)\nand in the [MCP Registry](https://registry.modelcontextprotocol.io) as\n`io.github.cybersmurf/stalwart-mail-mcp`, so no checkout is needed:\n\n```json\n{\n  \"mcpServers\": {\n    \"stalwart-mail\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"stalwart-mail-mcp\"],\n      \"env\": {\n        \"STALWART_URL\": \"https://mail.example.com\",\n        \"STALWART_USER\": \"jane@example.com\",\n        \"STALWART_PASSWORD\": \"…\"\n      }\n    }\n  }\n}\n```\n\nClaude 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`\n\n### Claude on the web, desktop chat and phone\n\nRun the server next to Stalwart (`stalwart-mail-mcp --http`, or the Docker image) and add its\nURL as a custom connector — step by step in [docs/remote.md](docs/remote.md).\n\n## Configuration\n\n| Variable | Meaning |\n|---|---|\n| `STALWART_URL` | public address of the server, e.g. `https://mail.example.com` (required) |\n| `STALWART_USER` | the mailbox you sign in as (required) |\n| `STALWART_PASSWORD` | mailbox or app password — sent as Basic auth |\n| `STALWART_TOKEN` | an OAuth access token instead of the password — sent as Bearer |\n| `MAIL_LANG` | `auto` (default: the machine's language, English when unsupported) or a locale code |\n| `MAIL_TOOL_PREFIX` | prefix of the tool names, default `mail` |\n| `MAIL_BRAND` | display name of the server, default `Stalwart Mail` |\n| `MAIL_DOWNLOAD_DIR` | where attachments are saved, default `~/Downloads/Mail-Attachments` |\n| `MAIL_TIMEZONE` | IANA zone for dates in the output, default the machine's zone |\n| `MAIL_OCR_PROVIDER`, `MAIL_OCR_API_KEY`, `MAIL_OCR_MODEL`, `MAIL_OCR_BASE_URL` | who reads scans — see [OCR providers](#ocr-providers) |\n| `MISTRAL_API_KEY` | shortcut: with only this set, scans go to Mistral OCR |\n| `MAIL_ALLOW_SEND` | `false` removes `send_email` and `send_draft` |\n| `MAIL_ALLOW_DRAFTS` | `false` removes `create_draft` and `delete_draft` |\n| `MAIL_ALLOW_CONTACT_EDIT` | `false` removes `add_contact` |\n| `MAIL_ALLOW_ATTACHMENTS` | `false` removes `get_attachment` |\n| `MAIL_SAVE_ATTACHMENTS` | `false` = opened attachments are only read, nothing is written to disk |\n\n## What it is allowed to do\n\nEvery capability is a switch in the extension settings (or an env variable above), all on by\ndefault. A capability that is off is **not offered as a tool at all**, so it holds regardless\nof what the client's approval prompts remember:\n\n- sending off → a mailbox Claude can read and draft in, but never send from;\n- sending, drafts and contact edits off → a read-only mailbox;\n- saving attachments off → `get_attachment` reads the file from a temporary copy and is\n  annotated read-only; with saving on it writes to the download folder and is annotated as a\n  writing tool, which clients may treat differently when asking for approval.\n\nApprovals themselves (\"allow once / always allow\") belong to the client, not to this server.\nIn Claude Desktop they are set per tool in the extension's settings; a client may ask again\nafter an update that changes a tool's definition.\n\n## Attachments and OCR\n\n`mail_get_attachment` downloads the file and returns what the model can read:\n\n- text files as text, HTML converted to text;\n- PDFs as text page by page (`page_from` / `page_to` for long ones);\n- PDF pages without a text layer (scans) and photos go to the **OCR provider** you choose —\n  the result is markdown including tables, and those pages are marked `(OCR)`. A mixed PDF\n  sends only its scanned pages;\n- images are returned as images; anything above ~600 kB or in HEIC is downscaled on macOS\n  (`sips`);\n- other types (docx, xlsx, zip…) are only saved, and the path is returned.\n\nWithout a provider, or with `ocr: false`, a scan comes back as an image of page 1 (macOS) with\na note. OCR is the only thing in this server that sends content anywhere besides your mail\nserver — to the provider you picked, or nowhere at all with a local model.\n\n### OCR providers\n\n| `MAIL_OCR_PROVIDER` | What it is | Needs | Reads PDFs |\n|---|---|---|---|\n| `auto` (default) | Mistral when `MISTRAL_API_KEY` is set, a custom server when address and model are set, otherwise off | — | — |\n| `mistral` | Mistral OCR (`mistral-ocr-latest`) | key | directly |\n| `anthropic` | Claude through the official SDK (default model `claude-opus-5-5`) | key | directly |\n| `openai`, `openrouter`, `gemini` | hosted OpenAI-compatible vision chat APIs | key + model | page images |\n| `ollama`, `lmstudio` | local models on `localhost` | model | page images |\n| `custom` | any other OpenAI-compatible server | `MAIL_OCR_BASE_URL` + model | page images |\n| `off` | no OCR | — | — |\n\n`MAIL_OCR_API_KEY`, `MAIL_OCR_MODEL` and `MAIL_OCR_BASE_URL` complete the choice. Examples:\n\n```bash\nMAIL_OCR_PROVIDER=ollama      MAIL_OCR_MODEL=llama3.2-vision                         # fully local\nMAIL_OCR_PROVIDER=openrouter  MAIL_OCR_API_KEY=…  MAIL_OCR_MODEL=<a vision model>\nMAIL_OCR_PROVIDER=anthropic   MAIL_OCR_API_KEY=…\nMAIL_OCR_PROVIDER=custom      MAIL_OCR_BASE_URL=http://nas.lan:8000/v1  MAIL_OCR_MODEL=…\n```\n\nProviders that take images only get each scanned page as a PNG taken out of the PDF (the\nscan itself, scaled to 2000 px). A page that is not one big picture cannot be handed to them\nand is reported as unread; Mistral and Anthropic read any PDF. Pages are sent three at a time.\n\nThings to expect: a local model can need a minute or more per dense page, which may exceed\nyour client's tool timeout — read long scans in page ranges. General vision models transcribe\nwell but, like every OCR, can misplace cells in tables with graphics; `preview: true` adds the\npage image so the model can check. With `anthropic`, a declined request is retried\nserver-side on a fallback model (`fallbacks: \"default\"`) on the current Claude models.\n\n`node test/live-ocr.mjs` runs the provider configured in the environment against a scanned\nfixture (or your own file) and prints the result.\n\n## Languages\n\nTool titles, descriptions, output and error messages are localized. English is the source,\nCzech is written by hand, and German, Spanish, French, Italian, Dutch, Polish, Portuguese and\nSlovak are **machine translations** that no native speaker has reviewed yet — corrections are\nwelcome.\n\nTo add or fix a language edit `src/locales/<code>.ts` (copy `en.ts`, keep the `{placeholders}`\nand line breaks) and register it in `src/locales/index.ts`. A locale may be partial; missing\nkeys fall back to English. `npm run test:offline` checks every locale against the English keys.\n\n## Branded builds (presets)\n\nFor a family or a team you can ship an extension where the server address is pre-filled and\npeople only type their e-mail and password. A preset is a folder with its own `manifest.json`\n(and optionally `icon.png`); see [presets/example](presets/example).\n\n```bash\n./pack.sh --preset /path/to/preset     # → /path/to/preset/<name>.mcpb\n```\n\nThe preset's manifest sets `MAIL_TOOL_PREFIX`, `MAIL_BRAND`, `MAIL_LANG` or\n`MAIL_DOWNLOAD_DIR` through `env`, and gives `server_url` a default. Keep the preset's `name`\nstable so Claude Desktop treats new builds as updates.\n\n## Tests\n\n```bash\nnpm run test:offline       # no mailbox needed: fake JMAP + fake OCR, the real server over stdio\nMISTRAL_API_KEY=… node test/offline.mjs --live-ocr    # also sends the fixtures to the real OCR\nSTALWART_URL=… STALWART_USER=… STALWART_PASSWORD=… node test/smoke.mjs          # real mailbox\nSTALWART_URL=… STALWART_USER=… STALWART_PASSWORD=… node test/smoke.mjs --send   # also sends a mail to yourself\n```\n\nThe offline test covers attachments, OCR, the tool prefix, language selection and locale\nconsistency. The smoke test creates a draft and deletes it; with `--send` it leaves one test\nmessage in the mailbox.\n\n## Good to know\n\n- **A wrong password gets the IP banned** by Stalwart after a few attempts. The server signs in\n  on the first tool call, not at start, so restarting the client does not cause bans; calling\n  tools repeatedly with a wrong password does.\n- Built for and used with Stalwart 0.16. The mail part is plain RFC 8620/8621 and may work with\n  other JMAP servers, but that is untested; contacts need JMAP for Contacts (RFC 9610).\n- `Email/query` with `\"inMailbox\": null` is rejected by Stalwart — the filter must be absent or\n  carry an id.\n- The extension bundle is one CommonJS file (~3.8 MB, most of it pdf.js from `unpdf`); the\n  `.cjs` extension matters because `package.json` says `\"type\": \"module\"`.\n- A tool result in Claude Desktop is capped at about 1 MB, hence the 600 kB limit for inline\n  images.\n\n## License\n\nMIT\n"}