MailFathom

What MailFathom MCP server does

The MailFathom MCP server keeps a local archive of mail from configured IMAP accounts and makes that archive available to MCP-compatible AI clients. PostgreSQL stores the synchronized copy, which MailFathom indexes for retrieval. This design lets agents answer questions from locally stored messages rather than querying the mailbox for every read.

The server covers both read and write workflows. Agents can inspect accounts, list or search messages, retrieve message content, and ask questions that cite the messages used for an answer. They can also change flags, create or update drafts, send messages, reply, forward, inspect queued outgoing mail, or cancel a send when the relevant account permissions allow those actions.

How it works

MailFathom imports mailbox data through IMAP and serves tools through the Model Context Protocol. Read operations use the database copy and report the freshness of that copy. They do not contact the mail server for each request and cannot set the remote read flag.

Outbound mail follows a separate path. A send is recorded and queued instead of being completed during the tool call. A delivery process attempts the send, and cancellation is possible only during the period before delivery leaves the system. Sending remains disabled unless it is enabled for the account and credential, and deployments configured as read-only reject it.

Search ranks lexical matches. Embedding-based similarity can also be used after an embedding model is configured. MailFathom stores its own contact records in the database; these are distinct from an address book maintained by the mail provider.

Setup and configuration

The recommended initial deployment uses Docker Compose. Its setup provisions PostgreSQL, publishes the services on loopback by default, asks for mailbox details, starts the stack, and can apply the database schema. The quick-start flow is intended for evaluation rather than production operation: its generated setup serves one machine over plain HTTP, keeps credentials under the checkout, and does not create backups.

The project also documents Compose, Podman Quadlet, Kubernetes, and a native systemd process. A local Aspire development path provisions PostgreSQL and applies the schema for developers working from the repository. After installation, the getting-started documentation covers connecting a chat client and making an initial tool call.

Tools and capabilities

The documented MCP surface contains 21 tools, grouped as follows:

• Read mail with list_accounts, list_emails, search_emails, get_email_content, and ask_mail.
• Apply read, unread, star, and keyword changes with set_mail_flags.
• Send, reply to, or forward messages with send_email, reply_to_email, and forward_email.
• Check or cancel queued delivery with get_outgoing_email and cancel_outgoing_email.
• Manage drafts with save_draft, update_draft, delete_draft, and send_draft.
• Use six tools for contacts stored in MailFathom's database.

The message-question tool includes citations for the messages used in its answer. Reply and forward operations derive addressing, subject, threading, quotation, and attachments from the stored message copy.

Limitations and notes

The MailFathom MCP server is under active development before version 1.0.0. Releases may change tools, configuration, database schema, or deployment behavior incompatibly, so operators should review the changelog before upgrades and keep a recoverable backup.

Sensitive content is not redacted by default when returned to a client; the README notes that redaction requires enabling SensitiveContent. Sending is off by default for each account, constrained by recipient policy and a configured per-period limit, and cannot be used to choose an arbitrary sender identity. The local archive's freshness depends on synchronization, so results should be interpreted with the freshness information returned by the server.