Krzysztof318/MailFathom

**A brain for your mail — self-hosted, AI-native, and yours alone.**
> [!WARNING]
> **MailFathom is under active development, and nothing between two releases is guaranteed to stay compatible until version 1.0.0.** Any release before it may change the MCP tools, the configuration, the database schema, or the deployment in a breaking way — up to a release that cannot run over the previous one's configuration or data at all. Read the changelog before every upgrade, and keep a backup you can go back to.
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.
That third line is the quick way to *try* it, not the way to run it: the script asks where your mailbox lives, writes the configuration, starts the stack, offers the schema step, records you and your mailbox, and hands you the key a chat client connects with — 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
| You are | Start at |
| --- | --- |
| Deciding whether MailFathom is for you | What it does well below, then the user guide |
| Installing or operating it | Installing MailFathom, then getting started |
| Connecting an agent to a running instance | Using the tools |
| Reading any of that with an AI assistant beside you | Hand it the documentation below |
| Contributing | CONTRIBUTING.md |
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:
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 /fathomise/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.
| | |
| --- | --- |
| **Reading your mail** | list_accounts, list_emails, search_emails — ranked lexically, and by embedding similarity once you configure a model — get_email_content for up to ten messages in full, and ask_mail, which answers a question from your mail and cites every message it drew on |
| **Marking it** | set_mail_flags marks a message read or unread, stars it, and writes the keywords your client shows as tags |
| **Sending** | send_email sends one message; reply_to_email and forward_email answer one you already hold, deriving the addressing, subject, threading, quotation, and attachments from your stored copy; get_outgoing_email and cancel_outgoing_email report what became of a send and stop one that has not left |
| **Drafting** | save_draft, update_draft, and delete_draft write a message into your own Drafts folder and send nothing at all; send_draft is what sends one |
| **Contacts** | Six tools over MailFathom's own book of people — not addresses — which lives in your database rather than at your mail provider |