An MCP server that lets an AI assistant read and file your email from the Maildir that mbsync already keeps on your machine. The server reads the folders and the configuration of the mbsync mailbox, without uploading anything on the internet.
mbsync keeps a local Maildir copy of your IMAP accounts in sync with the server, and mbsync-mcp works on that copy by exposing the mailbox through the Model Context Protocol, so that a client like Claude Code can list, read, search and file messages by calling tools.
Accounts, hosts and Maildir paths come from the
~/.mbsyncrc file you have stored on your computer. The server keeps no configuration of its own and reading your mail doesn't require any password.
As a personal project, this MCP server works on Linux and macOS, and on Windows only under WSL.
Source and instructions are available at:
github.com/leonardocppn/mbsync-mcp.
claude code
mbsync is a command-line application that syncs IMAP4 mailboxes onto your computer (saving them in Maildir format). Your usual email accounts (Gmail, Outlook, or anything else) are synced one at a time or all together, and then analysed by an AI agent through this MCP server.
The advantages of this MCP server are clear:
1. Once the emails are synced to disk, the data stays there and can be consulted offline.
2. The searches you can run are more powerful: you can search across several accounts at once, correlating messages far apart in time, drawing directly on their content rather than on their metadata.
3. MCP servers expose tools that an AI agent can use. mbsync-mcp is a Python script that can be extended at will with any function built for the purpose.
This server is not meant as a replacement for a proper email client. mbsync itself does not send email (that needs a separate SMTP tool, msmtp or similar), and the read tools work on the copy saved by the last sync. Unless you set up routines to sync periodically, it is not made to work in real time.
It is a powerful way to take proper stock of your mailboxes at specific points in the day.
The client starts server.py as a subprocess and talks to
it over standard input and output, using JSON-RPC. The server runs only for
as long as the client does.
Inside, the work splits in two. Reads never touch the network, they walk the Maildir on disk, which is fast and works offline. Writes go out over IMAP to avoid conflicts. The Maildir is a mirror of the mailbox on the server, so after each successful write mbsync-mcp runs mbsync for that account to bring the change into the local copy.
Besides the tools, the server publishes two MCP resources:
mbsync://accounts, and
mbsync://account/<name>/folders for each account
it finds in your configuration.
Reading mode:
- list_accounts
- Accounts found in
~/.mbsyncrc. - list_folders
- Folders available for an account, nested ones included.
- count_emails
- Total and unread count for a folder.
- get_emails
- Messages with filters: date range, unread only, limit, optional sync first.
- get_unread_emails
- The unread ones, newest first.
- get_email_details
- Full body, headers and the list of attachments.
- search_emails
- By sender, subject, body, or all three.
- get_inbox_summary
- Counts plus the senders you hear from most.
- daily_briefing
- The inbox summary plus the unread messages, optionally only those that arrived from a given day on.
Writing mode (the tools that move messages log in with your IMAP credentials):
- sync_account
- Runs mbsync for one account, with a timeout.
- move_email
- Between two folders.
- archive_email
- To the account’s archive folder, found on the server.
- delete_email
- To trash, again whatever the provider calls it.
- cleanup_batch
- Several deletes and archives over a single connection.
- list_operations
- The latest writes, each with its operation id.
- undo_operation
- Moves the messages of one operation (by default the latest) back where they were.
Linux or macOS (on Windows, under WSL); Python 3.10+; a working mbsync configuration; mcp>=1.0.0;
keyring (optional, for storing the IMAP password in the system keyring).
Point your client at the server. In Claude Code, that is an entry
in .mcp.json.
For the tools that move messages, mbsync-mcp reads the IMAP password from
the system keyring, or runs the account’s PassCmd from
~/.mbsyncrc when the keyring has no entry for the account.
To store the password in the keyring, run this once (for Gmail, use an
app password).
Source and instructions: github.com/leonardocppn/mbsync-mcp (MIT licence).
- October 2026
- Added IMAP timeout - Connections to the mail server now close after 30 seconds with no reply, so that a network drop no longer leaves the server blocked. Moves interrupted by a dropped connection are checked on the server and stay in the journal for undo_operation.