your-mail-mcp — Claude Code MCP server: what it does, how to install
A local read-only server that searches your IMAP mailboxes. It surfaces old invoices, agreements, and credentials directly into your AI assistant session.
claude mcp add --env PUBLIC_URL=<PUBLIC_URL> --env OAUTH_PASSPHRASE=<OAUTH_PASSPHRASE> --transport stdio your-mail-mcp -- docker run -i --rm -e PUBLIC_URL -e OAUTH_PASSPHRASE ghcr.io/wildsurfer/your-mail-mcp:0.4.0What your-mail-mcp does
The server mirrors IMAP accounts into a local maildir using mbsync and builds a full-text search index with notmuch. It answers tool calls entirely from this offline data. The AI reads email history without sending data to external hosted search engines.
Safety is enforced at the process level. The tool has no logic to send or delete messages. Its Go codebase contacts mail providers solely with the IMAP LIST command to detect spam and trash folder names, leaving message bodies untouched.
Docker is the only system requirement. Provider quirks need attention: Gmail requires an app password with two-factor authentication enabled, while iCloud rejects the full address and requires just the account name.
What it helps with
- locate booking references and Wi-Fi credentials across older messages
- pull project requirements from an email thread directly into a coding task
- track chronological agreements between parties in a message chain
- review unread incoming mail from multiple inboxes without write access
Example prompts for the agent
- Look up the confirmation code for the hotel reservation I made last month.
- Extract the client design specifications from the recent email exchange.
- Give me a summary of incoming work messages received overnight.
How to install your-mail-mcp
Platform CLI
claude mcp add --env PUBLIC_URL=<PUBLIC_URL> --env OAUTH_PASSPHRASE=<OAUTH_PASSPHRASE> --transport stdio your-mail-mcp -- docker run -i --rm -e PUBLIC_URL -e OAUTH_PASSPHRASE ghcr.io/wildsurfer/your-mail-mcp:0.4.0Replace <…> with your own values
Platform CLI
codex mcp add your-mail-mcp --env PUBLIC_URL=<PUBLIC_URL> --env OAUTH_PASSPHRASE=<OAUTH_PASSPHRASE> -- docker run -i --rm -e PUBLIC_URL -e OAUTH_PASSPHRASE ghcr.io/wildsurfer/your-mail-mcp:0.4.0Replace <…> with your own values
Config file
{
"mcpServers": {
"your-mail-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"PUBLIC_URL",
"-e",
"OAUTH_PASSPHRASE",
"ghcr.io/wildsurfer/your-mail-mcp:0.4.0"
],
"env": {
"PUBLIC_URL": "<PUBLIC_URL>",
"OAUTH_PASSPHRASE": "<OAUTH_PASSPHRASE>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"your-mail-mcp": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"PUBLIC_URL",
"-e",
"OAUTH_PASSPHRASE",
"ghcr.io/wildsurfer/your-mail-mcp:0.4.0"
],
"env": {
"PUBLIC_URL": "<PUBLIC_URL>",
"OAUTH_PASSPHRASE": "<OAUTH_PASSPHRASE>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e PUBLIC_URL=<PUBLIC_URL> -e OAUTH_PASSPHRASE=<OAUTH_PASSPHRASE> your-mail-mcp docker run -i --rm -e PUBLIC_URL -e OAUTH_PASSPHRASE ghcr.io/wildsurfer/your-mail-mcp:0.4.0Replace <…> with your own values
Step 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 your-mail-mcp
How to install your-mail-mcp in Claude Code?
Run `claude mcp add --env PUBLIC_URL=<PUBLIC_URL> --env OAUTH_PASSPHRASE=<OAUTH_PASSPHRASE> --transport stdio your-mail-mcp -- docker run -i --rm -e PUBLIC_URL -e OAUTH_PASSPHRASE ghcr.io/wildsurfer/your-mail-mcp:0.4.0`. Make sure to provide values for the required environment variables.
How does your-mail-mcp protect email security?
It operates entirely in read-only mode and lacks routines to draft, alter, or remove mail. Messages are mirrored locally via mbsync and queried through notmuch, so LLM agents cannot modify remote mailbox contents.
What credentials are required for Gmail and iCloud accounts?
Gmail accounts need two-factor authentication and an application password instead of the main account password. For iCloud, specify only the account username rather than the complete address ending in @icloud.com.
