MailFathom

A brain for your mail — self-hosted, AI-native, and yours alone.

MailFathom synchronizes your IMAP accounts into a PostgreSQL database you run, indexes that copy, and serves it to AI agents as tools over the Model Context Protocol. Reading answers from your copy rather than from a mail server, and it never marks anything read there. Writing — marking, drafting, sending — is a separate act each account and each credential has to be given, and every one of them is off until you turn it on.

One question, answered from the local copy in an ordinary chat client. The *** in these screenshots were blacked out by hand before the files entered a public repository — until you turn SensitiveContent on, MailFathom redacts nothing on its way to a client.

Install

Docker Compose is the recommended first installation. It is the only shape that provisions PostgreSQL for you, and its defaults publish both ports on loopback, so nothing is reachable from another machine until you decide it should be.

git clone https://github.com/Krzysztof318/MailFathom.git
cd MailFathom
scripts/quick-start-compose.sh

That third line is the quick way to try it, not the way to run it: the script asks where your mailbox lives, generates the credentials, writes the configuration, starts the stack, offers the schema step, and hands you the address a chat client connects to — and what it prepares serves that one machine over plain HTTP, keeps its credentials in files under the checkout, and backs nothing up. It prints that list when it finishes.

Installing MailFathom is the real thing: what every shape needs, and the guide for Compose, Podman Quadlet, Kubernetes, or a native systemd process. Getting started then walks from an installed instance to a first successful tool call. To evaluate from the checkout instead, the local Aspire orchestration provisions PostgreSQL and applies the schema on its own — local development has that path.

Start here

Hand the documentation to your agent

If an AI assistant is helping you install, configure, or use MailFathom, give it the documentation rather than a search over the site. One line is the whole of it:

Read https://krzysztof318.github.io/MailFathom/llms.txt and follow it to the pages that answer my question.

That address is the current release's map: every published page, what it answers, and a link to its source, so the agent fetches the one page that owns your question instead of fragments of several. MailFathom also resolves in Context7 as /krzysztof318/mailfathom, which mirrors the default branch rather than a release.

→ Handing this guide to your own agent

What an agent gets

Twenty-one tools, and they are the whole surface.

Two properties hold everywhere, and much of the design follows from them:

• Reading is local. A read answers from your copy and never contacts a mail server, so it is fast, it works while the server is down, and it changes nothing remotely. Every result states how fresh the local copy is.
• Nothing writes unless you asked for it. Retrieval cannot set the remote \Seen flag at all. What can change your mailbox is what you configured — a mail rule, a spam action — or a tool a credential was explicitly granted. Sending is stricter again: it is off on every account, refused outright while the deployment is read-only, and bounded by a recipient policy and a per-period ceiling you set.

No send is performed while the caller waits. Each is written down, answered with a record identity, and offered by a delivery pass that survives a crash — so a message MailFathom says it queued is one it will actually try to deliver, and the seconds before it leaves are the only window in which it can be withdrawn. Nothing a client sends decides who a message is from.

Beside what a tool returns, MailFathom records what it can establish about each message: who authenticated its sender and whether you recognize that author, how much its text reads as machine written, and the conversation it belongs to. What each tool answers, refuses, and never repeats back is the contract.

Project status

0.7.0 is the current release, and it is the first one that sends mail. Before it, everything an agent could reach read your local copy; from here it can compose a message, answer one you already hold, forward one on, leave a draft for you, and mark or label mail on your server.

Upgrading from 0.6.0 takes a configuration edit and a database migration you apply. The important one: a credential entry that names no permissions holds everything its surface publishes, so on upgrade it gains the ability to send from your mailboxes — write the grant you mean on every entry. The changelog states each break against the surface it breaks, and what to do about it; the schema step applies while 0.6.0 is still serving.

Nightly images are built from main and published beside the releases. A nightly is not a release: its schema can be ahead of any published migration, it has no upgrade path in either direction, and it is deleted once newer ones accumulate. What a nightly build risks states the whole of it.

Read the full README on GitHub →