Stalwart Mail MCP
Allows using local Ollama-hosted vision models as an OCR provider for scanned PDF pages, accepting page images and returning transcribed markdown without sending content to a cloud service.
Allows using OpenAI-compatible vision chat APIs as an OCR provider for scanned PDF pages, accepting page images and returning transcribed markdown.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Stalwart Mail MCP search my inbox for unread emails from this week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Stalwart Mail MCP
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).
Tool | What it does |
| accounts (own + shared), folders with counts, allowed senders, address books |
| full text / from / to / subject / folder / date / unread / has attachment, or a whole thread |
| a whole message by id (HTML → text) with a numbered list of attachments |
| an attachment's content: text, PDF page by page, OCR of scans and photographed documents, images; saves the file to disk |
| send a new mail or a reply ( |
| the same, but only saved to Drafts |
| send / delete a draft by id |
| address books of every account plus senders and recipients from the mail history |
| new contact (own or shared address book) |
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.
Related MCP server: postbus-mcp
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 → InstallFill 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
Variable | Meaning |
| public address of the server, e.g. |
| the mailbox you sign in as (required) |
| mailbox or app password — sent as Basic auth |
| an OAuth access token instead of the password — sent as Bearer |
|
|
| prefix of the tool names, default |
| display name of the server, default |
| where attachments are saved, default |
| IANA zone for dates in the output, default the machine's zone |
| who reads scans — see OCR providers |
| shortcut: with only this set, scans go to Mistral OCR |
|
|
|
|
|
|
|
|
|
|
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_attachmentreads 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_tofor 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
| What it is | Needs | Reads PDFs |
| Mistral when | — | — |
| Mistral OCR ( | key | directly |
| Claude through the official SDK (default model | key | directly |
| hosted OpenAI-compatible vision chat APIs | key + model | page images |
| local models on | model | page images |
| any other OpenAI-compatible server |
| page images |
| no OCR | — | — |
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>.mcpbThe 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 yourselfThe 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/querywith"inMailbox": nullis 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.cjsextension matters becausepackage.jsonsays"type": "module".A tool result in Claude Desktop is capped at about 1 MB, hence the 600 kB limit for inline images.
License
MIT
Available Tools
10 toolsmail_add_contactAdd a contactA
Creates a contact in an address book. Default is the signed-in mailbox's own address book; pass the account of a shared mailbox to store it in the shared one (everyone with access sees it, on phones too through CardDAV). Check mail_search_contacts first so you do not create a duplicate.
Inputs: note, given, title, emails, +7 more.
mail_create_draftCreate a draftA
Saves a message as a draft in the Drafts folder (does not send). The user can then review it in webmail or on the phone and send it themselves, or mail_send_draft sends it by id. Same parameters as mail_send_email (including replying via in_reply_to_id and attachments).
Inputs: cc, to, bcc, from, +8 more.
mail_delete_draftDelete a draftADestructiveIdempotent
Permanently deletes a draft by id. Works only on messages flagged as drafts — it never deletes sent or received mail.
Inputs: id (required), account.
mail_get_attachmentOpen an attachmentAIdempotent
Downloads an attachment of a received message, saves it to disk and returns its content: text for text files, the text of every page for PDFs, the picture for images. Scans (PDF pages without a text layer) and photos of documents are read through OCR, tables included; pages that came from OCR are marked “(OCR)” — treat numbers from them with some caution and ask for a preview when a figure matters. Other types (docx, xlsx, zip…) only return the path of the saved file. Pick the attachment by name or by its number from the list in mail_get_email; a message with a single attachment needs neither. The message itself is not changed.
Inputs: id (required), ocr, account, page_to, +4 more.
mail_get_emailRead a messageARead-onlyIdempotent
Returns a whole message by id (from mail_search_emails): headers, body text (HTML is converted to text) and the list of attachments. mail_get_attachment reads an attachment's content (PDF, image, text). To reply use mail_send_email with in_reply_to_id. Changes nothing (does not mark the message as read).
Inputs: id (required), html, account.
mail_list_mailboxesFolders, accounts and sendersARead-onlyIdempotent
Returns the available accounts (your mailbox plus shared ones), folders with message counts (unread) and the addresses you can send from. Call it first when you do not know which folders or accounts exist. Changes nothing.
Inputs: account.
mail_search_contactsFind a contact / addressARead-onlyIdempotent
Finds an e-mail address or phone number: searches the address books (your own and shared ones) and also the mail history (who wrote to you and whom you wrote to, matching the query). Use it whenever you need a person's or company's address before sending anything. Without a query it lists the whole address book.
Inputs: limit, query, account, include_history.
mail_search_emailsSearch messagesARead-onlyIdempotent
Searches mail (full text, sender, recipient, subject, folder, date, unread, attachments) or lists a whole thread. Returns message ids (for mail_get_email), thread, sender, date and a preview. Newest first, paging through limit/offset. Without a filter it returns the latest messages from all folders (trash included) — for “what is new” use mailbox="inbox", unread=true.
Inputs: to, from, text, after, +9 more.
mail_send_draftSend a draftA
Sends an existing draft by id (from mail_create_draft or from a search in the drafts folder). Sends immediately — only on the user's explicit instruction.
Inputs: id (required), from, account.
mail_send_emailSend an e-mailA
Sends an e-mail from the mailbox — a new one, or a reply (in_reply_to_id). A copy is stored in Sent. It sends IMMEDIATELY and cannot be undone. Send only when the user explicitly said the message should go out; otherwise create a draft (mail_create_draft). Verify the recipient before sending — never guess an unknown address, look it up with mail_search_contacts.
Inputs: cc, to, bcc, from, +8 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool maps to a distinct resource+action: listing mailboxes, searching, fetching a message, fetching an attachment, sending, draft lifecycle (create/send/delete), and contact search/add. Boundaries are clear, with draft-sending vs email-sending distinguished by tool name and description.
Every tool follows a strict mail_verb_noun pattern (mail_list_mailboxes, mail_search_emails, mail_get_email, mail_create_draft, etc.). No mixing of conventions or verb styles.
10 tools is well-scoped for a mail server spanning folders, messages, attachments, drafts, and contacts. Each tool clearly earns its place with no redundancy.
Core lifecycle is well covered: read/search/attachments, send, full draft lifecycle (create/send/delete), and contact search/add. Gaps remain around managing received mail (move, archive, mark read/unread) and contact update/delete, but agents can work around most of these.
Maintenance
Related MCP Connectors
Hosted email MCP for your own Gmail, Outlook.com, Microsoft 365, iCloud or IMAP inbox: read, search, draft, reply in thread, forward and file mail. It moves or flags up to 500 messages in one call, and a send leaves exactly one copy in Sent. A calendar is a separate connection, and connecting one adds diary and scheduling tools.
Private, EU-hosted email for AI agents over JMAP: read, search, reply, draft, organize, send.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Hosted MCP server for your Gmail, Outlook and IMAP mail, with mailboxes and scopes set per agent.
Related MCP Servers
- FlicenseNot gradedqualityBmaintenanceMCP server exposing JMAP email and Sieve script operations as tools, enabling mailbox management, email creation, search, flagging, and Sieve script management.2-
- AlicenseNot gradedqualityBmaintenanceEnables searching, reading full conversations, and sending email across multiple IMAP/SMTP mailboxes from any MCP client, with multi-user support and per-user API tokens.MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI clients to connect to a self-hosted IMAP/SMTP mailbox for searching, reading, sending, organizing, and managing email messages and folders through authenticated MCP tools.MIT
- AlicenseNot gradedqualityCmaintenanceEnables authenticated MCP clients to list, search, read, flag, draft, and optionally send mail from one Gmail or Microsoft 365 mailbox using OAuth without app registration.MIT