MailFathom — Claude Code MCP server: what it does, how to install
Syncs IMAP mailboxes into a local PostgreSQL database for AI agents. Searches messages, provides cited answers, and handles drafting or sending.
Open on GitHubWhat MailFathom does
The server pulls messages from IMAP accounts into a self-hosted PostgreSQL database. AI agents query this local archive directly instead of communicating with mail servers. Incoming messages stay unread at the source. Write actions remain disabled until granted per account, preventing unexpected drafts or flags.
Mail reading tools include lexical search and ask_mail, which provides answers alongside cited messages. Tools like reply_to_email automatically extract threads and recipients from stored data. Sensitive values pass without redaction unless you enable SensitiveContent.
Until version 1.0.0 arrives, schema updates can break compatibility, making manual backups necessary before upgrades. Initial evaluation uses scripts/quick-start-compose.sh to launch PostgreSQL and the service over Docker Compose on loopback ports.
What it helps with
- mirror IMAP mailboxes into a local PostgreSQL database
- search email archives using text and semantic embedding queries
- answer user questions with citations from specific emails
- draft and send threaded email replies using stored conversation context
- update message flags and tags without modifying unread states on the mail server
Example prompts for the agent
- Use
ask_mailto check recent vendor correspondence and summarize invoices with citations. - Find unread messages from last week using
list_emailsand summarize the key threads. - Draft a response to the latest contract inquiry using
reply_to_email.
How to install MailFathom
1Template address
The server address is a template: replace {…} or […] with your own values
2Platform CLI: remote server
claude mcp add --transport http mailfathom https://{mailfathom_host}/mcp1Template address
The server address is a template: replace {…} or […] with your own values
2Platform CLI: remote server
codex mcp add mailfathom --url https://{mailfathom_host}/mcp1Template address
The server address is a template: replace {…} or […] with your own values
2Config file
{
"mcpServers": {
"mailfathom": {
"url": "https://{mailfathom_host}/mcp"
}
}
}1Template address
The server address is a template: replace {…} or […] with your own values
2Config file
{
"servers": {
"mailfathom": {
"type": "http",
"url": "https://{mailfathom_host}/mcp"
}
}
}1Template address
The server address is a template: replace {…} or […] with your own values
2Platform CLI: remote server
gemini mcp add -t http mailfathom https://{mailfathom_host}/mcpStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about MailFathom
How do I install MailFathom in Claude Code?
Run claude mcp add --transport http mailfathom https://{mailfathom_host}/mcp, replacing {mailfathom_host} with your running host address. Ensure your Docker Compose stack or system service is active first.
What does MailFathom do?
MailFathom replicates IMAP mailboxes into a local PostgreSQL database and provides agent tools to search archives, cite specific messages, and send or manage email.
Does the server modify messages on the remote IMAP host?
No, reading tools only touch the local PostgreSQL replica and never mark emails as read on the remote server. Modifying flags or sending messages requires explicitly granted permissions for each account.
