<img src="https://raw.githubusercontent.com/Krzysztof318/MailFathom/main/assets/icon-900.png" alt="MailFathom logo" width="120">

MailFathom

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

A mailbox is the largest archive most people own and the least usable one. Contracts, decisions, invoices, threads that ended without a conclusion, attachments nobody will ever find again: all of it is in there, and none of it is reachable except by scrolling. Mail clients are built to show you the newest of it, one message at a time. After twenty years of accumulation, that is the wrong shape entirely.

MailFathom is being built to change what mail is to software. It synchronizes your IMAP accounts into a PostgreSQL database you run, keeps that copy current, indexes it so the whole of it is reachable rather than only its most recent slice, and serves it to AI agents as tools over the Model Context Protocol. The destination is a mail brain: something an agent can put a question to and get an answer from, working across years of mail, on infrastructure that belongs to you.

MCP is how agents reach MailFathom; it is not what MailFathom is. The protocol surface is deliberately thin, and the project is building what sits behind it — continuous synchronization, extracted and indexed content, lexical search today, semantic retrieval and question answering next, and eventually the ability to act on your mail rather than only read it. Where it is going is the current direction in full.

None of it depends on somebody else's service. The copy is yours, the database is yours, the deployment is yours, and the AI capabilities on the roadmap arrive as providers you choose and point at rather than as ones compiled into the product.

What exists today

What is implemented is read-only synchronization and three tools, and this README is split on that line: this section and What it does well describe the code as it stands, while Where it is going is the roadmap.

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

• Reading is local. A tool call answers from your copy and never contacts a mail server, so it is fast, it works while the server is down, and it cannot change anything remotely. Every result states how fresh the local copy is.
• Synchronization never writes to your mailbox. Fetching mail never sets the remote \Seen flag, so mail MailFathom has copied still shows as unread in your own mail client until you read it there.

What an agent gets is three tools, and they are the whole surface:

Tool	What it answers
list_emails	A page of the timeline, newest first, filtered by account, folder, sender, recipient, subject, date range, seen state, or attachment presence
search_emails	Ranked matches for a text query across subjects, participants, and body text, each with short extracts around what matched
get_email_content	Up to ten messages in full: normalized headers, plain-text body, optionally sanitized HTML, and attachment names, types, and sizes — never attachment bytes

A connected agent can list, read, and search your mail. It cannot send, delete, move, or mark anything, because no such tool exists on the surface. That describes this stage rather than a permanent limit: writing is on the roadmap, starting with sending, and each write capability will arrive as its own tool behind a reviewed authorization and confirmation flow — never as a setting that loosens a tool you already trust.

Start here

You are	Start at
Deciding whether MailFathom is for you	What it does well below, then [the user guide](https://github.com/Krzys