Repository avatar
AI Tools
v0.1.0
active

langmail-mcp

io.github.langmail/langmail-mcp

Self-hosted MCP server for Stalwart: email, calendar and contacts over JMAP, CalDAV and CardDAV.

Documentation

Langmail MCP for your own Stalwart: email, calendar and contacts

langmail-mcp is an open-source MCP server (Model Context Protocol) for people who run a self-hosted Stalwart mail server. It gives an AI agent the email, calendar and contacts tools of Langmail's hosted MCP server, and works against your own Stalwart over JMAP, CalDAV and CardDAV. It runs on your computer or on your server and talks only to your Stalwart; no Langmail service is involved.

Not affiliated with Stalwart Labs.

The first release is pending. langmail-mcp is not on npm yet, so npx -y langmail-mcp does not work today. Until it is, run the server from a clone: git clone https://github.com/langmail/langmail-mcp.git, cd langmail-mcp, npm ci, npm run build, and use node /path/to/langmail-mcp/dist/index.js wherever this document says npx -y langmail-mcp.

What you can ask an agent to do with it

An agent connected to this server can search and read your mail, write drafts and send them, file and label messages, manage mail rules, and work with your calendars and contacts. The following prompts are examples of what that makes possible:

  • "Find the email from the landlord about the heating repair. It was some time in 2023 and I cannot find it."
  • "Summarise the conversation with the accountant about the tax return: what is done, what is still open, and what is waiting on my reply."
  • "Draft a reply to Anna that proposes two free slots next week, and leave it in my drafts for me to review."

Reading mail does not mark it as read. Sending mail, unsubscribing and changing a meeting that other people are invited to cannot be undone, so it is sensible to have the agent confirm those with you first.

Install

The server needs Node.js 22 or later. There is nothing to install by hand: an MCP client starts the server with npx -y langmail-mcp, which downloads the package on first use. To have the langmail-mcp command available permanently, for example on a server, install it globally:

npm install -g langmail-mcp

Configure

All configuration comes from environment variables. The server checks them when it starts and refuses to start with a message that names what to set. Nothing has a default that points to a host other than your own.

VariableRequiredDefaultMeaning
STALWART_URLyesBase URL of your Stalwart, for example https://mail.example.com. JMAP, CalDAV and CardDAV are reached under it. Use https://; the server warns about http:// to any host but the local machine.
STALWART_USERNAMEwith STALWART_PASSWORDThe account's login name, usually its mail address.
STALWART_PASSWORDwith STALWART_USERNAMEAn app password for that account (see Creating a Stalwart app password).
STALWART_TOKENinstead of username and passwordA bearer token, for example a Stalwart API key. Set either this or the username and password, not both.
MCP_TRANSPORTnostdiostdio or http. The command-line arguments --http and --stdio do the same and take precedence.
MCP_AUTH_TOKENin HTTP modeThe secret callers must send as Authorization: Bearer <secret>. At least 16 printable ASCII characters without spaces.
MCP_HOSTno127.0.0.1HTTP mode: the address to listen on.
MCP_PORTno8080HTTP mode: the port to listen on.
MCP_PUBLIC_URLbehind a reverse proxyhttp://<MCP_HOST>:<MCP_PORT>HTTP mode: the address callers reach the server under, for example https://mcp.example.com.
LOG_LEVELnowarnfatal, error, warn, info, debug, trace or silent. info adds one line per tool call. Logs go to stderr.
LANGMAIL_MCP_ALLOW_UNSUBSCRIBE_POSTnooffSet to 1 to let unsubscribe_from_list send a one-click unsubscribe request to the sender's URL.
LANGMAIL_MCP_ALLOW_REMOTE_IMAGESnooffSet to 1 to let preview_email load a message's remote images through this server.

.env.example lists the same settings with comments.

Your Stalwart must advertise the same public URL you set as STALWART_URL (same scheme, hostname and port). The server sends your credential to that address only: if Stalwart names another one for its JMAP or CalDAV endpoints, for example http:// behind a TLS proxy or an internal hostname, the tool call fails with a message naming both addresses and nothing is sent to the other one.

Connect an agent

The server speaks MCP over two transports. Over stdio, the MCP client starts the server as a child process, which fits an agent that runs on the same computer. Over Streamable HTTP, the server runs on its own and the agent connects to it by URL, which fits an agent on a server.

On the same computer, over stdio

Most MCP clients read a JSON configuration of this shape. The file's name and location depend on the client.

{
	"mcpServers": {
		"langmail": {
			"command": "npx",
			"args": ["-y", "langmail-mcp"],
			"env": {
				"STALWART_URL": "https://mail.example.com",
				"STALWART_USERNAME": "you@example.com",
				"STALWART_PASSWORD": "your-app-password"
			}
		}
	}
}

For Claude Desktop, this is the content of claude_desktop_config.json, which opens from Settings, Developer, Edit Config. For Claude Code, one command adds the server:

claude mcp add langmail \
  -e STALWART_URL=https://mail.example.com \
  -e STALWART_USERNAME=you@example.com \
  -e STALWART_PASSWORD=your-app-password \
  -- npx -y langmail-mcp

The server does not contact Stalwart when it starts. A wrong URL or password therefore shows up on the agent's first tool call, not at start-up.

On a server, over Streamable HTTP

In HTTP mode the server listens at /mcp, on 127.0.0.1:8080 by default. It refuses to start without MCP_AUTH_TOKEN, and every caller must send that secret as Authorization: Bearer <token>. Any other request to /mcp is answered with 401 and no data. openssl rand -hex 32 generates a suitable secret.

export STALWART_URL=https://mail.example.com
export STALWART_USERNAME=you@example.com
export STALWART_PASSWORD=your-app-password
export MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
npx langmail-mcp --http
# langmail-mcp: listening on http://127.0.0.1:8080/mcp

GET /healthz answers ok without the token, for a process supervisor or a load balancer to check.

To keep the server running, a systemd unit along these lines can be used. The environment file holds the variables above, one NAME=value per line, and should be readable only by the service's user (chmod 600).

# /etc/systemd/system/langmail-mcp.service
[Unit]
Description=Langmail MCP for Stalwart
After=network-online.target
Wants=network-online.target

[Service]
EnvironmentFile=/etc/langmail-mcp.env
ExecStart=/usr/bin/npx -y langmail-mcp --http
Restart=on-failure
User=langmail-mcp

[Install]
WantedBy=multi-user.target

The default address is reachable from the same machine only, which is enough for an agent that runs on that machine. The server speaks plain HTTP. For that reason, TLS must be terminated by a reverse proxy before the server is exposed beyond loopback; otherwise the token and your mail travel unencrypted. With Caddy, which obtains the certificate itself, the configuration is:

mcp.example.com {
	reverse_proxy 127.0.0.1:8080
}

Behind a reverse proxy, MCP_PUBLIC_URL must be set to the address callers use, here https://mcp.example.com. The server only accepts requests addressed to a loopback name or to the host of MCP_PUBLIC_URL, as a protection against DNS rebinding, and answers 403 to a proxied request when the variable is missing. The links the attachment tools hand out are created under the same address.

A client then connects to a remote HTTP server with a bearer header. In Claude Code's .mcp.json format, which several other clients share:

{
	"mcpServers": {
		"langmail": {
			"type": "http",
			"url": "https://mcp.example.com/mcp",
			"headers": {
				"Authorization": "Bearer your-mcp-auth-token"
			}
		}
	}
}

The equivalent Claude Code command is:

claude mcp add --transport http langmail https://mcp.example.com/mcp \
  --header "Authorization: Bearer your-mcp-auth-token"

There is no OAuth flow. A client that can only connect to remote servers through OAuth, and cannot send a fixed header, cannot use this server over HTTP.

Creating a Stalwart app password

An app password is a separate password for one application, which can be revoked without changing the account's main password. Stalwart calls it by that name. Each user creates their own in Stalwart's account manager, which is served under /account on your Stalwart (for example https://mail.example.com/account). Stalwart shows the generated password once, so copy it when it is created. Stalwart's documentation describes the steps and the options: App passwords.

Set STALWART_USERNAME to the account's login name and STALWART_PASSWORD to the app password. The server signs in with HTTP Basic authentication. Alternatively, set STALWART_TOKEN to a Stalwart API key, which is sent as a bearer token.

Tools

The server registers 40 tools. Their names and inputs are the same as on Langmail's hosted server, so the Langmail documentation describes what each one does and how they fit together: https://docs.langmail.me/reference/mcp/overview. Their descriptions are the same too, except for a few sentences that are only true of the hosted service. A test compares every definition with the hosted server's and lists each of those rewordings: src/mcp/hosted-parity.test.ts.

GroupTools
Mailsearch_emails, get_email, get_thread, preview_email, archive_emails, move_emails, trash_emails, mark_emails, unsubscribe_from_list
Drafts and sendingcreate_draft, get_draft, list_drafts, update_draft, delete_draft, send_draft, reply_to_message, forward_message
Attachmentsdownload_attachment, download_email, upload_attachments
Mail rulespreview_mail_rule, create_mail_rule, list_mail_rules, update_mail_rule, delete_mail_rule
Calendarlist_calendars, create_calendar, update_calendar, list_calendar_events, create_calendar_event, update_calendar_event, delete_calendar_event, move_calendar_events, respond_to_event
Contactssearch_contacts, list_upcoming_birthdays, create_contact, update_contact, delete_contact, merge_contacts

Differences from Langmail's hosted server

The tools behave as they do on the hosted server wherever a plain Stalwart allows it. The differences below follow from two facts: this server has no Langmail service behind it, and it sends nothing to a third party unless you turn that on.

  • Calendar sharing is left out. share_calendar and stop_sharing_calendar hand out calendar feed links that Langmail's hosted service and database serve. This server has neither, so the two tools do not exist here, and list_calendars shows no sharing information.
  • One-click unsubscribe is off by default. The one-click request of RFC 8058 goes to a URL the sender chose. unsubscribe_from_list sends it only when LANGMAIL_MCP_ALLOW_UNSUBSCRIBE_POST=1 is set. Otherwise the tool returns the unsubscribe link or address for you to use yourself.
  • Remote images are not loaded by default. preview_email renders a message without its remote images unless LANGMAIL_MCP_ALLOW_REMOTE_IMAGES=1 is set. When it is, this server fetches the images and passes them on, so the sender sees the server's address and not the address of the device that shows the preview.
  • Attachment links are served by this server. download_attachment, download_email and upload_attachments hand out short-lived URLs. In HTTP mode they are under MCP_PUBLIC_URL. In stdio mode the server listens on a local port on 127.0.0.1 for them, so they only work on the same computer.
  • Searching by email type needs a classifier. Langmail's hosted classifier labels each message with a type (invoice, ticket, newsletter and so on), and the keywords filter of search_emails matches those labels. Nothing writes them on a plain Stalwart mailbox, so a type filter matches nothing there. The to-do label is different: mark_emails sets it itself, so the agent finds what it marked. Search by text, sender, date, folder, read state and star works as usual.
  • archive_emails needs an Archive folder. Langmail creates one for every account. A new Stalwart account may not have one, and the tool then says so. Create a folder with the Archive role once, in your mail client or in Stalwart.
  • Contacts are not collected from mail. Hosted Langmail collects the people you correspond with from mail headers in a background service, which this server does not have. The Collected address book grows only from the calendar tools, i.e. from the people you schedule with or reply to an invitation from. Contacts that you or the agent create, and anything synced over CardDAV, work the same.
  • You sign in with your own Stalwart login. The hosted server uses Langmail's OAuth. This server uses an app password or a bearer token for your Stalwart account.

Privacy: what leaves your machine

The server's invariant is that nothing leaves your computer or server except traffic to your own Stalwart, unless you turn it on. Two settings turn something on, and both default to off: LANGMAIL_MCP_ALLOW_UNSUBSCRIBE_POST (a request to a sender's unsubscribe URL) and LANGMAIL_MCP_ALLOW_REMOTE_IMAGES (requests to the hosts a message's images are on). Your Stalwart credential is sent only to the origin of STALWART_URL, never to another address a server answer or a redirect names. A previewed email is shown under a content security policy that lets it load images from this server and nothing from anywhere else, so the sender's CSS cannot make your client fetch from the sender. There is no telemetry, no error reporting service and no update check. Logs go to stderr only and carry neither credentials nor message content.

However, this covers the server and not the agent. Whatever a tool returns goes to the MCP client that asked for it, and from there to the model that client uses. If that model runs at a provider, the mail the agent reads passes through that provider.

Requirements

  • Node.js 22 or later.
  • A Stalwart server with an account you can sign in to. The server is tested end-to-end in CI against a real Stalwart at the version in .stalwart-version, currently 1.1.1. Other versions may work but are not tested.

Development

git clone https://github.com/langmail/langmail-mcp.git
cd langmail-mcp
npm ci
cp .env.example .env   # then fill in your own values
npm run dev            # runs src/index.ts with .env, restarting on changes

npm run build compiles to dist/, npm test runs the unit tests, and npm run check:fix formats and lints with Biome. npm run validate runs everything CI checks except the end-to-end suites: lint, unit tests, unused-code check and build. npm run test:e2e runs the suites in e2e/ against a real Stalwart; e2e/README.md describes how to start one locally, with or without docker.

Contributing, security and license

Contributions are welcome; CONTRIBUTING.md describes the workflow and the commit convention, and CODE_OF_CONDUCT.md applies. Please report vulnerabilities privately as described in SECURITY.md, not in a public issue. The code is released under the MIT license.

NPM
langmail-mcp
Install Command
npm install langmail-mcp