mailbox-mcp — Claude Code MCP server: what it does, how to install
Connects Gmail, IMAP, and JMAP mailboxes to your AI workflow. Reads threads, drafts replies, and filters hidden prompt injections.
claude mcp add mailbox-mcp -e MAILBOX_MCP_PASSPHRASE=<MAILBOX_MCP_PASSPHRASE> -- npx -y mailbox-mcpWhat mailbox-mcp does
mailbox-mcp exposes mail accounts to MCP clients without running separate processes for each inbox. It handles standard Gmail API connections alongside generic IMAP/SMTP setups and JMAP providers such as Fastmail. The suite includes 49 tools covering search, attachments, filters, drafts, and label management.
Reading messages exposes models to untrusted inputs, so the server wraps raw email content in nonced boundaries. Hidden styles, zero-size fonts, off-screen text, and control characters are stripped before reaching the model. If content was deleted, the server warns about the character count. Outbound traffic is constrained by default to 10 sends per minute and 100 per day.
Stored credentials rely on AES-256-GCM encryption, meaning MAILBOX_MCP_PASSPHRASE is mandatory at startup. For strict security, accounts can run in draftsOnly mode or require confirmation in an interactive terminal via /dev/tty.
What it helps with
- search across work and personal inboxes inside terminal workflows
- draft contextual email responses without leaving the editor
- strip concealed prompt injections and invisible characters from incoming mail
- enforce manual confirmation on outbound mail to unknown recipients
Example prompts for the agent
- Find all unread invoices received this week across my configured accounts
- Draft a reply to the latest client thread in my Fastmail mailbox
- Summarize recent unread notifications and apply the archive label
How to install mailbox-mcp
Platform CLI
claude mcp add mailbox-mcp -e MAILBOX_MCP_PASSPHRASE=<MAILBOX_MCP_PASSPHRASE> -- npx -y mailbox-mcpReplace <…> with your own values
Platform CLI
codex mcp add mailbox-mcp --env MAILBOX_MCP_PASSPHRASE=<MAILBOX_MCP_PASSPHRASE> -- npx -y mailbox-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"mailbox-mcp": {
"command": "npx",
"args": [
"-y",
"mailbox-mcp"
],
"env": {
"MAILBOX_MCP_PASSPHRASE": "<MAILBOX_MCP_PASSPHRASE>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"mailbox-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mailbox-mcp"
],
"env": {
"MAILBOX_MCP_PASSPHRASE": "<MAILBOX_MCP_PASSPHRASE>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e MAILBOX_MCP_PASSPHRASE=<MAILBOX_MCP_PASSPHRASE> mailbox-mcp npx -y mailbox-mcpReplace <…> 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 mailbox-mcp
How do I install mailbox-mcp in Claude Code?
Run claude mcp add mailbox-mcp -e MAILBOX_MCP_PASSPHRASE=<MAILBOX_MCP_PASSPHRASE> -- npx -y mailbox-mcp with your chosen encryption passphrase.
What does mailbox-mcp do?
It connects email providers such as Gmail, IMAP, and JMAP to your AI agent. Tools allow searching, reading, drafting messages, and organizing labels.
How does mailbox-mcp prevent prompt injection attacks?
It strips hidden HTML elements and invisible unicode characters before returning data. Untrusted email bodies are enclosed in random nonces, and outbound actions to unseen addresses trigger confirmation checks.
