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 read-only tools over the Model Context Protocol. Reading answers from your copy rather than from a mail server, and reading never marks anything read on the server — only a rule or a spam action you configured yourself can change your mailbox.

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

From there, installing MailFathom covers what every shape needs — Linux, PostgreSQL with the vector extension, an IMAP account, an explicit schema step — and routes you to 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: provisioning the secrets, configuring a mailbox, applying the schema, verifying health, enabling the MCP endpoint, and connecting a client.

To evaluate MailFathom from the checkout instead of deploying it, the local Aspire orchestration provisions PostgreSQL and applies the schema on its own. Local development has that path.

Related MCP server: io.github.p-w-4-z/inbox-mcp

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, its title, and one line saying what it answers, linking each page's Markdown source. The agent loads the map in full and then fetches only the page that owns your question, so its answer comes from the page carrying the contract instead of from fragments of several. The map also names the two bundles beside it — the operator path, from choosing an installation to administering the deployment, and the mailbox user path, from connecting a client to what each tool returns — for when the question is a whole path rather than one page of it. Every version the site documents carries its own copy of all three, and the address above is the version the site opens on.

MailFathom also resolves in Context7, as /krzysztof318/mailfathom, for an agent that already has that connector. It is a mirror and the map above is what it mirrors: it indexes the default branch rather than a release, so it can answer from documentation of work no version carries yet, and it is refreshed on its own schedule rather than by a publish here.

→ Handing this guide to your own agent

What exists today

What is implemented is read-only retrieval, five tools, and the rules and spam actions your own configuration turns on, 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.

• Retrieval 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 can write is what you configured to: a MailRules rule whose action moves, copies, deletes, or marks a message read, and SpamClassification:Actions, which files junk and marks it read. Both are off until you turn them on, and each account states which of the four actions a rule may ask of it.

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

The first four are always there. ask_mail needs a chat model and an embedding model you configure and point at, so a deployment with neither does not advertise it at all rather than offering a tool that would fail on first use.

The screenshot at the top of this page is list_emails. Two of the other tools, answering the same client over the same mailbox:

A connected agent can list, read, search, and ask about your mail. It cannot send, delete, move, or mark anything, because no such tool exists on the surface — including inside an answering run, which is composed with one capability and that capability searches. 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.

Project status

0.6.0 is the current release, and it builds on 0.5.0 — ask_mail, semantic ranking in search_emails, list_accounts, and the ceilings on what answering and embedding may spend.

• What it adds is everything that acts on your mail rather than reading it: rules you author in configuration that move, copy, delete, and mark messages as read; spam classification that can file junk on the server; and the durable queue underneath both. Beside that, mail can be redacted before anything is derived from it or leaves the deployment, secrets found in the process and personal data by an analyzer you run beside it. The rules, the classification, and both scanners are off until you turn them on; the queue beneath the first two runs on every instance. The MCP surface is still the same five read-only tools, exactly as the paragraph above says: nothing a client can call writes to a mailbox.

• Upgrading from 0.5.0 is a configuration edit, a client edit, and a database migration you apply. Every folder you want read is named in configuration, and mail under an alias your file no longer names is unreachable until an entry names it again; switching a folder's Synchronize off now keeps its stored mail instead of erasing it; the folder argument of list_emails, search_emails, and ask_mail is folders where it was folderAliases, and the old spelling is ignored rather than refused, so a client still sending it reads every folder instead of the one it named; get_email_content hands back a signed link per attachment instead of base64, asked for with includeAttachmentDownloadLinks where 0.5.0 asked with includeAttachmentContent, and issues none unless Deployment:PublicBaseAddress is declared; EmailContent:MaxAttachmentBytes and EmailContent:MaxAttachmentBytesPerRead are deleted from the configuration file, or the host declines to start on a key it no longer knows; and mail in a folder mapped as junk is withheld from listing and search unless the call asks for it, and withheld from answering with no way to ask. The schema step applies while 0.5.0 is still serving. The changelog states each break against the surface it breaks, and what to do about it.

• What it ships is a container image, a Helm chart, the SQL script that creates the schema it expects, and an mfctl binary per platform — where the artifacts are published has the references. There is no binary artifact for the service itself, so a native installation starts from a checkout of this repository.

• What it promises across the MCP tool contract, the configuration schema, the database schema, and the deployment contract is stated in the changelog.

Nightly images are built from main and published to both registries alongside 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 before you choose one.

Where the artifacts are published

Both registries carry the same manifest list under the same digest, so the one to pull from is whichever your environment already reaches. The image and the chart each carry a signed provenance statement; the container image records what each tag means and how to verify one.

What it does well

MailFathom is built as an enterprise-grade system from the first line, even while its feature scope is still small. Every claim below is a property of the code and the deployment assets today, and each links to the page that documents it.

Nothing on the surface writes, and no setting changes that

• The MCP surface is five tools — list_accounts, list_emails, get_email_content, search_emails, ask_mail — and that is all of it. There is no write tool to enable, and nothing a client sends can change your mailbox.

• Retrieval is incapable of marking remote mail as read. A change to your mailbox happens only where your own configuration asks for one — a rule action, or a spam action — never because a caller asked.

• No response carries an attachment's bytes. A call that asks for them by name receives a signed link per file instead, valid for minutes, scoped to that one attachment, and resolved through the live mailbox so it dies with the message it points at.

• Configuration is read-only to the process, permanently. No request, command, or tool changes a setting, and the service never rewrites the file it was configured from. So the file you provisioned is the file in force: how an instance is configured is reviewable as a diff and restorable from a backup, and nothing reachable over the network can move it out from under you. What the service itself has to modify lives in the database instead.

→ MCP tools, configuration sources

Secure by default, and explicit about every weakening

• The MCP endpoint is off until you enable it, and enabling it means stating whether it requires an API key or nothing at all. The unauthenticated posture is legal, announced with a startup warning, and never the default.

• Client certificates and per-client rate limits are part of the endpoint rather than something a proxy has to add.

• IMAP is TLS-on-connect by default, and a private certificate authority is trusted rather than validation disabled. A configuration that weakens the transport or sends a clear-text credential fails startup unless it says so explicitly.

→ The MCP endpoint, transport security

Credentials never live in configuration

• A secret-bearing setting holds a reference — a file path, a systemd credential, an environment variable — and the material lives wherever the deployment provisions it.

• A configuration file is therefore safe to review, diff, and back up: leaking it leaks paths, not passwords.

→ Secret provisioning, rotation

Mail is handled as personal data by the code that touches it

• Content, metadata, extracted text, and search extracts are never written to a log and never carried in an error message.

• Every call is bounded — at most 100 summaries in a page, 50 ranked matches in a search, a configured character bound on a body — so a deployment can decide how much mail a single call may draw out.

• That is the part software can settle. Whether a deployment satisfies GDPR depends on how you run it: where the database sits, who reaches it, how long you keep mail, and which model an agent hands a result to. What MailFathom offers is an architecture that keeps those choices open rather than one that has already made them badly, including explicit seams for the data-subject workflows a later release implements.

→ Using the tools

It fails fast and says why

• Startup resolves every secret reference and verifies the database schema before the process serves anything, and a refusal names the configuration key or the pending migration that caused it.

• Migrations are never applied while starting, in any environment — applying is a step you take, with a backup first.

• Three probes answer on a listener of their own, and telemetry is OpenTelemetry, exported only where you point it.

→ Health endpoints, configuration reference, telemetry

The deployment assets are hardened, not illustrative

• The image is chiseled — no shell, no package manager, no HTTP client — runs as an unprivileged user on a read-only root filesystem with every Linux capability dropped, creates no diagnostic socket, and carries no tool that could apply a migration.

• Docker Compose, the Podman Quadlet units, and the Helm chart all ship that posture by default, and the chart meets the Restricted Pod Security Standard.

• The Quadlet shape goes one step further on secrets: because a .container file is a systemd unit source, the deployment's credentials are encrypted at rest and bound to the machine, decrypted only as the unit starts.

→ The container image, Compose, Podman Quadlet, Kubernetes

The supply chain is verifiable

• Images are multi-architecture, built from base images pinned to an exact patch version, scanned before publication, and accompanied by signed build provenance that ties a digest to the commit and workflow that produced it.

• Package versions are pinned centrally with committed lock files, and every third-party component is reviewed against a licensing policy that keeps the project commercially redistributable.

→ Verification, THIRD_PARTY_LICENSES.md

It is built to be maintained

• A .NET 10 clean-architecture modular monolith, with enforced boundaries between domain, application, infrastructure, protocol, and host.

• Compiler and analyzer diagnostics are errors, and every behavior change ships with tests.

• The decisions that shape the system are recorded as ADRs rather than remembered.

→ Solution structure, decisions

Documentation

Every documentation link on this page goes to the documentation site, which is the readable form: the same pages with search, an API reference generated from the source, and a version selector. It opens on the current release, and an address here names no version, so a link keeps working across releases and lands on the one you are most likely to be running. docs/ is the index for reading the same pages in the repository instead. The ones you are most likely to want first:

Documentation under docs/ describes behavior that exists. Where something is planned, it is tracked as an issue rather than written up as though it worked.

Why it exists

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 keeps the local copy current, indexes it so the whole of it is reachable rather than only its most recent slice, and serves it to agents as tools. 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 and semantic retrieval, question answering over both, and eventually the ability to act on your mail rather than only read it.

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.

Where it is going

The five tools are the foundation, not the product. What follows turns a synchronized, searchable copy of your mail into something an agent can reason over and eventually act on. The direction is set and the order is not fixed:

• Acting on mail, not only reading it. Sending is the first write capability: a durable SMTP outbox exists as an application capability before it is ever an MCP tool, and exposing it waits on a reviewed authorization and confirmation flow, because a tool that sends mail is a different security question from one that reads it. Every later write capability takes the same route. MailFathom can already perform a change against a mailbox and record what it did, and since 0.6.0 your own rules and the spam classification ask it to — what this step adds is a caller on the other side of the protocol, which is the different security question.

Ideas, not yet scope

These are recorded as open questions, each waiting on a decision rather than on effort. Discussions is where they are argued, and the Ideas category is open to yours.

• Encrypted and signed mail, S/MIME and OpenPGP — the hard part is not the parsing but whether local decryption should be permitted at all, since it turns end-to-end protected mail into searchable plaintext. #75

• Antivirus scanning of stored attachments, constrained by which engines can be used under a permissive licensing policy. #77

• OAuth for outbound IMAP and SMTP, so a provider that has retired password authentication stays reachable. #78

• Skill-based jobs, whose body is an instruction an agent carries out against a slice of your mail, rather than the deterministic rule 0.6.0 shipped. It asks questions a rule does not — what content leaves for a model, what a job may act on, and what an attacker who can write you an email can make one do.

Contributing

Contributions are welcome, and the entry point is CONTRIBUTING.md: it gets you from a clone to a passing verification run and states the few rules a pull request has to satisfy. Every change starts from an issue, so open one — or comment on an existing one — before writing code, and wait for a reply on anything larger than a typo, because MailFathom is on its 0.x line and its direction still moves faster than its issue list.

MailFathom is developed AI-first, and close to zero-touch. Nearly every line here was written by an autonomous coding agent working from an issue and the rules in AGENTS.md, and reviewed before merge; the maintainer sets direction and decides, but rarely edits code by hand. Working the same way is encouraged rather than merely tolerated — point an agent at your checkout, let it read the instruction files, and let it produce the change, its tests, and its documentation in one pass. A hand-written patch is judged identically. What does not change either way is that you read your diff before submitting it, and that the same gates and the same licensing obligations apply. How this project is built has the whole of it.

docs/operations/local-development.md is the full development setup, AGENTS.md is the entry point to the engineering rules the build and the review enforce, and CODE_OF_CONDUCT.md applies to everyone taking part.

Your first contribution, from a fork to a green run

Fork the repository, then clone your fork and point it at this one, because every verification gate here measures your branch against the base it will actually merge into rather than against your fork's main:

git clone https://github.com/<you>/MailFathom.git
cd MailFathom
git remote add upstream https://github.com/Krzysztof318/MailFathom.git
git fetch upstream main

If you work with a coding agent, hand the rest to get-started-contributors, which is one of the workflow skills this repository ships and the one written for somebody arriving for the first time. In Claude Code it is /get-started-contributors; any other agent can be pointed at the file. It welcomes you and walks through what MailFathom is, how this repository is worked, where things live, and what Apache-2.0 asks of a contribution — then sets the machine up: the platform check, the .NET SDK the global.json pin accepts, gh, Docker, the local file that tells your agent it is working in a fork rather than in the maintainer's checkout, the permissions your agent needs so the verification loop stops asking on every command, and a first green run. Invoke it again weeks later and it refreshes that machine against what has changed here since, rather than walking you through any of it twice. You invoke it yourself — it is deliberately not something an agent starts on its own.

Setting up by hand takes the same steps in the same order, and From a clone to a green run is where they are written out. Development is on Linux; nothing here is verified against anything else.

Questions, bugs, and proposals

Discussions takes questions in Q&A and proposals in Ideas; a question is not a unit of work, and one that turns out to be work gets converted into an issue. A defect or a piece of scope belongs in issues — except a vulnerability, which has a private channel below.

Security

MailFathom holds mailbox credentials, OAuth tokens, certificate material, and a local copy of someone's mail. Report a vulnerability privately through SECURITY.md rather than in a public issue.

Privacy policy. MailFathom transfers no information to other networked systems unless specifically requested by the user or the person installing or operating it. It reaches the mail servers, the database, and the model provider a deployment configures, and nothing else: it collects no telemetry, phones no home, and exports OpenTelemetry data only to an endpoint an operator sets. Where mail is stored, who can reach it, and which model receives a result are deployment decisions — SECURITY.md and the user guide describe them, and the terms of any model provider a deployment chooses are that provider's own.

Verifying what you downloaded

No mfctl binary carries a code signature, on any platform, so Windows warns about an unknown publisher when you run one. The checksum file attached beside them is what tells a genuine download from a tampered one, and checking it is a deliberate step rather than something the operating system does for you:

sha256sum --check --ignore-missing 'mfctl-<version>.sha256'

The administrative endpoint is where getting the command and verifying it are documented.

The container image and the Helm chart are different: each carries a signed build provenance statement naming the workflow and commit that produced it, so gh attestation verify answers where one came from without your having to trust the registry. The container image records how to check one.

License

MailFathom is licensed under the Apache License, Version 2.0, SPDX identifier Apache-2.0. Source files repeat that grant in a header the build enforces, and a published artifact carries LICENSE and NOTICE beside the binaries. The container image is that same publish output, so it carries both files and declares org.opencontainers.image.licenses; the Helm chart states the identifier as artifacthub.io/license.

MailFathom was originally created by Krzysztof Kasprowicz. The root NOTICE records that attribution, which section 4(d) of the license asks a derivative distribution to preserve while it remains relevant to the derived work. A fork may add its own attribution notices beside it. The notice adds no use restriction, changes nothing about the license, and claims nothing about contributions written by other copyright holders.

Contributions to this repository are offered under Apache-2.0, by section 5 of the license. There is no contributor licence agreement and no developer certificate of origin, and contributors keep the copyright in what they write.

Third-party components that MailFathom consumes are reviewed separately in THIRD_PARTY_LICENSES.md. That register records what MailFathom depends on and under which terms; it grants nothing in MailFathom itself, which LICENSE alone does.

The application icon in assets/ is MailFathom's own asset rather than a third-party component, and the same grant covers it. The register records how it was produced and why no one else holds rights in it.

What the license grants, it grants without promising that the software works. Sections 7 and 8 give MailFathom as is, without warranties or conditions of any kind, and state that no contributor is liable for damages arising out of its use or out of an inability to use it — a synchronization that falls behind, a search that misses what was there, or mail disclosed by a deployment that was reachable when it should not have been. That is the ordinary allocation for software given away rather than sold, and the license text is what governs rather than this summary of it: read sections 7 and 8 before pointing MailFathom at a mailbox that matters. Where the database sits, who can reach it, how long mail is kept, and which model receives a result stay the deployment's decisions, and they are where most of the risk actually lives.