chainmail
Provides email integration for Gmail accounts, enabling agents to read and search mail, manage folders and labels, and send or draft messages under chainmail's policy and audit controls.
Supports Google Workspace email accounts via OAuth, allowing account setup and login through Google for agent-driven email operations.
Supports Hostinger email accounts, enabling agents to read, search, organize, send, and draft mail through the policy daemon.
Supports iCloud email accounts, enabling agents to read, search, organize, send, and draft mail through the policy daemon.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
chainmail is email for AI agents, behind a policy daemon.
Why
The daemon owns every password and token, in an age-encrypted vault, and no call ever returns one.
A send to anyone off the allowlist is saved as a draft for you to review, never sent.
Nearly every call is recorded in an append-only audit log.
Agents reach the daemon over MCP, behind the same policy and audit log as the CLI.
flowchart LR
A[AI agent] -- MCP over stdio --> M[chainmail mcp]
C[chainmail CLI] -- ConnectRPC --> S((Unix socket))
M -- ConnectRPC --> S
S --> D[chainmail daemon]
D --- V[(vault)]
D --- P{policy}
D --- L[(audit log)]
D --- K[(cache)]
D -- IMAP --> I[mail servers]
D -- SMTP --> IRelated MCP server: readNdraft IMAP MCP
Install
brew install yaklabco/tap/chainmail
chainmail versionHomebrew installs the binary, its shell completions and its man page. It does not start the daemon; chainmail bootstrap does. Release archives, Nix and building from source are on the install page.
Set up
chainmail bootstrap sets up a production daemon that runs as its own user, with one account. Run it as yourself, not as root. It asks for sudo once.
chainmail bootstrap you@example.comBootstrap finds the provider from the address. It supports Gmail, Google Workspace, iCloud and Hostinger. --provider names one when the address does not show it. Bootstrap prints its plan, asks for the account's app password, and asks you to confirm. A Google Workspace account needs --oauth-client-id, and bootstrap asks for the OAuth client secret instead. Bootstrap then creates the chainmail user (_chainmail on macOS) and the chainmail-clients group. It installs the binary, the config, the vault key and the service. It starts the daemon, stores the password and tests the login. --dry-run prints the plan and changes nothing. A rerun adds another account or repairs the install.
When bootstrap makes a new vault key, it asks whether to back it up. The default is no backup. The key then stays on this machine, and only the daemon's user can read it. If the key is lost, nothing can read the stored passwords, but no mail is lost. If the vault key is lost says how to recover. The other choice shows the key once on the terminal, for you to save in a password manager. Anything that can see the terminal at that moment sees the key too, including an agent watching the session. --key-backup none or --key-backup show answers the question in advance.
Bootstrap adds you to chainmail-clients. Log out and back in, or run newgrp chainmail-clients, before you use chainmail. The account is named after the address's local part, you here, unless --name picks another:
chainmail accounts list
chainmail folders --account you
chainmail search is:unread in:inboxOn macOS, bootstrap also writes your cli.toml so commands find the daemon's socket. Bootstrap supports Linux with systemd, NixOS and macOS. On NixOS it works differently.
An agent that can run sudo without a password can get around all of this. Run agents from an account that cannot.
The quick start goes on to Google accounts, sends and the policy, watching and items.
On NixOS
On NixOS, the NixOS module runs chainmail, and bootstrap writes the files that configure it. Bootstrap never edits your NixOS configuration and never rebuilds. It never starts or restarts the daemon either.
chainmail bootstrap you@example.com --nix-dir ./chainmail-nixosBootstrap writes three files into --nix-dir, which is ./chainmail-nixos by default. chainmail.nix turns on the module and adds you to chainmail-clients. chainmail-you.nix holds the account. chainmail-vault-key.cred is the vault key, sealed with systemd-creds. On a machine with a TPM2 it opens only on that machine. Without one, it opens wherever the host key in /var/lib/systemd/credential.secret is, a file only root can read. None of the files holds a secret in the clear, so you can commit them.
Import the files from your NixOS configuration and add the chainmail flake input. Bootstrap prints the lines to add. Rebuild the way you normally do. Then run bootstrap again with the same address. It stores the password through the daemon and tests the login.
A second account works the same way. Bootstrap writes only that account's file, chainmail-<name>.nix, and needs no sudo for it. Import the file, rebuild, and run bootstrap again.
If the vault key is lost
Bootstrap does not make a new key while the old vault is still there, because a new key could never open it. The error says the vault /var/lib/chainmail/vault.age exists but the vault key /etc/chainmail/vault-key does not.
If you saved the key, put it back. Paste it into a file called vault-key, install that file as the daemon's key with mode 0400, and delete the copy. Then run bootstrap again to check the install and start the daemon:
sudo install -o chainmail -g chainmail -m 0400 vault-key /etc/chainmail/vault-key
rm vault-key
chainmail bootstrap you@example.comOn macOS, use -o _chainmail -g chainmail-clients instead.
Without a saved key, the stored passwords and logins cannot be recovered. Move the old vault aside, then run bootstrap again:
sudo mv /var/lib/chainmail/vault.age /var/lib/chainmail/vault.age.lost
chainmail bootstrap you@example.comBootstrap makes a new key and asks for that account's password again. Run it once more for each other account, with the same address and options as before, to enter its password again. For an OAuth account, bootstrap asks for the OAuth client secret again and logs in through the browser. Without a terminal it cannot log in, and it tells you to run chainmail auth login <name>.
On NixOS, the key is the sealed credential chainmail-vault-key.cred in your NixOS configuration, and bootstrap does not make a new one while the module is installed. A reinstall that loses /var/lib/systemd/credential.secret, or a new TPM2, means the credential no longer opens. If you saved the key, put it in a file called vault-key in the directory that holds the old credential, and seal it again on this machine. The new credential replaces the old one only after it decrypts to a valid age identity, and the saved copy is deleted only after that. Then commit the new file and rebuild:
sudo nix shell nixpkgs#age -c bash -euo pipefail -c '
systemd-creds encrypt --name=vault-key vault-key chainmail-vault-key.cred.new
systemd-creds decrypt --name=vault-key chainmail-vault-key.cred.new - | age-keygen -y >/dev/null
mv chainmail-vault-key.cred.new chainmail-vault-key.cred' && rm vault-keyWithout a saved key, stop the daemon, move the old vault aside, and seal a new key in place of the old credential. Run the commands below in the directory that holds the old credential. One root shell makes the new key with age-keygen and pipes it straight into systemd-creds. The key never passes through a process of yours and is never shown. The new credential replaces the old one only after it decrypts to a valid age identity. Commit the new file and rebuild, which starts the daemon again. Then run bootstrap once for each account to enter its password again:
sudo systemctl stop chainmail
sudo mv /var/lib/chainmail/vault.age /var/lib/chainmail/vault.age.lost
sudo nix shell nixpkgs#age -c bash -euo pipefail -c '
age-keygen 2>/dev/null | systemd-creds encrypt --name=vault-key - chainmail-vault-key.cred.new
systemd-creds decrypt --name=vault-key chainmail-vault-key.cred.new - | age-keygen -y >/dev/null
mv chainmail-vault-key.cred.new chainmail-vault-key.cred'Developing chainmail
chainmail daemon --dev runs a daemon as your own user, for work on chainmail itself:
dev mode: this daemon runs as you, so any program running as you, including agents, can read the vault key and every stored password. Use it only to develop chainmail, never with real accounts.
chainmail daemon --dev --config ./config.toml --state-dir ./state \
--vault-key-file ./vault-key --socket ./state/chainmail.sockThe developer guide covers building and testing.
Features
Reading and search:
folders,search,get,threadandattachmentacross every account, with Gmail-style operators. Reading never marks mail read.Sending and drafts:
send,send-raw,reply,forwardanddraft, with Markdown bodies, attachments, dry runs and idempotency keys.Organizing: move, copy, archive, trash, flags, Gmail labels and folders, with refs piped in from a search.
The send policy: sends off the allowlist are held as drafts, and
expungeandfolder deleteare refused unless the config allows them.The audit log: an append-only table in
state.db, read withchainmail audit, that never holds message content or secrets.MCP:
chainmail mcpserves the tools to an AI agent over stdio.Watching and events: IMAP IDLE and polling feed a durable event log, and a named group resumes where it stopped.
The local cache:
cache.db, indexed with SQLite FTS5, answers searches and reads when it is complete and fresh.Work items: a tree of items from objectives down to tasks, with mail threads linked to them and events when they come due.
Rules: rules in
state.dblabel, file, forward and archive mail as it arrives, on a schedule or on demand. They match with the search language against the cache, and each action is audited.Calendars:
calendars,agenda,event,invites,invite,rsvpandfreebusyread calendars and answer invites on Google accounts and CalDAV servers.event create,event editandevent cancelchange events under the send policy.NixOS module: runs the daemon as its own system user, with the vault key passed as an encrypted systemd credential.
Calendars
chainmail reads and answers calendars on Google accounts through the Google Calendar API, and on CalDAV servers such as Mailwright. The daemon syncs them into calendar.db, next to cache.db, every 5 minutes by default. Ten MCP tools give agents the same calls, such as agenda, rsvp and create_event.
Each account's
[accounts.<name>.calendar]table setsstoretogoogle,caldavornone. A Google account that logs in with OAuth2 defaults togoogle, and every other account defaults tonone.The cache finds invites in the new mail of every watched account. On an account with store
none,chainmail rsvpanswers them with an iCalendar REPLY email to the organizer.A Google account with store
googleasks for three calendar scopes. A token from before calendars lacks them, so mail keeps working and calendar calls fail withAUTH_REQUIREDuntil you runchainmail auth login <account>.A Mailwright account uses the
customprovider withauth = "oauth2"and an OAuth client that has anissuer, such as a Keycloak realm. Its calendar table setsstore = "caldav"and the server'surl.The send policy checks every answer and every change that notifies anyone else. A held answer through the calendar changes nothing, and a held answer by email is saved to Drafts. A new event with an attendee off the allowlist becomes a draft event that invites no one, and you send its invitations from your calendar app.
chainmail watch --kind invite,event_changed,event_cancelled,invite_replyreports new invites and changes to your events.
Documentation
The manual is at chainmail.sh.
Getting started: install, a first daemon, accounts and connecting an agent.
User guide: reading, sending, organizing, items, rules, calendars, watching, the audit log and CLI settings.
Agents: setting up an MCP client and working with mail as an agent.
Operations: deploying, health checks, auth, upgrades, backups and troubleshooting.
Reference: configuration, commands, MCP tools and exit codes.
Developer guide: architecture, building, testing, the API and releasing.
Status
chainmail is in active development. Releases are published on GitHub and in the yaklabco/homebrew-tap tap, and the changelog lists what each one changed.
License
chainmail is released under the MIT license. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
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.
Read, send, file and search email in any Gmail, Microsoft 365 or IMAP mailbox, plus its calendar.
Read, send, organize, watch email on any IMAP mailbox: Gmail, iCloud, OVH, Zoho, Fastmail + CalDAV.
Email and meetings for AI agents you can trust: checked mail, held sends, Meet calls you approve.
Related MCP Servers
- AlicenseAqualityDmaintenanceLocal MCP server for multi-account IMAP/SMTP email (iCloud + Gmail via app-specific passwords). Never marks mail read. Cross-folder search, idempotent sends, TLS verified.835 PyPIMIT
- AlicenseAqualityBmaintenanceSafely searches, reads, flags, and drafts email through IMAP, with no send, delete, or move capabilities. Uses a local broker and OS credential store for secure authentication.16Apache 2.0
- AlicenseNot gradedqualityCmaintenanceLets MCP clients read, search, draft, move, label, and delete mail through a locally running Proton Mail Bridge connection, so messages never leave your machine. Sending is off by default, deletions only move mail to Trash, and draft attachments are restricted to approved folders.105 npmMIT
- AlicenseNot gradedqualityCmaintenanceA local server that lets Claude Desktop or Claude Code read, search, triage and draft messages, view and add calendar events, and look up or create contacts, all signing in with a single Apple app-specific password. It defaults to drafting rather than sending and offers a read-only mode, plus recipient allowlists, so nothing changes or leaves your account unless you explicitly allow it.PolyForm Noncommercial 1.0.0