Skip to main content
Glama
Stalwart Mail MCP
by cybersmurf

Stalwart Mail MCP

Česky

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

mail_list_mailboxes

accounts (own + shared), folders with counts, allowed senders, address books

mail_search_emails

full text / from / to / subject / folder / date / unread / has attachment, or a whole thread

mail_get_email

a whole message by id (HTML → text) with a numbered list of attachments

mail_get_attachment

an attachment's content: text, PDF page by page, OCR of scans and photographed documents, images; saves the file to disk

mail_send_email

send a new mail or a reply (in_reply_to_id, reply_all), attachments from disk

mail_create_draft

the same, but only saved to Drafts

mail_send_draft / mail_delete_draft

send / delete a draft by id

mail_search_contacts

address books of every account plus senders and recipients from the mail history

mail_add_contact

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 → Install

Fill 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

STALWART_URL

public address of the server, e.g. https://mail.example.com (required)

STALWART_USER

the mailbox you sign in as (required)

STALWART_PASSWORD

mailbox or app password — sent as Basic auth

STALWART_TOKEN

an OAuth access token instead of the password — sent as Bearer

MAIL_LANG

auto (default: the machine's language, English when unsupported) or a locale code

MAIL_TOOL_PREFIX

prefix of the tool names, default mail

MAIL_BRAND

display name of the server, default Stalwart Mail

MAIL_DOWNLOAD_DIR

where attachments are saved, default ~/Downloads/Mail-Attachments

MAIL_TIMEZONE

IANA zone for dates in the output, default the machine's zone

MAIL_OCR_PROVIDER, MAIL_OCR_API_KEY, MAIL_OCR_MODEL, MAIL_OCR_BASE_URL

who reads scans — see OCR providers

MISTRAL_API_KEY

shortcut: with only this set, scans go to Mistral OCR

MAIL_ALLOW_SEND

false removes send_email and send_draft

MAIL_ALLOW_DRAFTS

false removes create_draft and delete_draft

MAIL_ALLOW_CONTACT_EDIT

false removes add_contact

MAIL_ALLOW_ATTACHMENTS

false removes get_attachment

MAIL_SAVE_ATTACHMENTS

false = opened attachments are only read, nothing is written to disk

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_attachment reads 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_to for 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

MAIL_OCR_PROVIDER

What it is

Needs

Reads PDFs

auto (default)

Mistral when MISTRAL_API_KEY is set, a custom server when address and model are set, otherwise off

—

—

mistral

Mistral OCR (mistral-ocr-latest)

key

directly

anthropic

Claude through the official SDK (default model claude-opus-5-5)

key

directly

openai, openrouter, gemini

hosted OpenAI-compatible vision chat APIs

key + model

page images

ollama, lmstudio

local models on localhost

model

page images

custom

any other OpenAI-compatible server

MAIL_OCR_BASE_URL + model

page images

off

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>.mcpb

The 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 yourself

The 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/query with "inMailbox": null is 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 .cjs extension matters because package.json says "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 tools
mail_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 draftA
DestructiveIdempotent

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 attachmentA
Idempotent

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 messageA
Read-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 sendersA
Read-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 / addressA
Read-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 messagesA
Read-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

    A4.4/5.0

    Scored across 10 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      B
      maintenance
      MCP server exposing JMAP email and Sieve script operations as tools, enabling mailbox management, email creation, search, flagging, and Sieve script management.
      2
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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