Mailbox MCP

mailbox-mcp

Give your AI tools access to your email. Search, read, send, and manage messages across multiple accounts without leaving your terminal.

mailbox-mcp is an MCP server that connects your email to Claude Code, Cursor, Windsurf, or any AI tool that supports the Model Context Protocol. Instead of switching between your terminal and Gmail, you ask the AI to find that invoice, summarize a thread, or draft a reply — and it does.

What makes this different from the 60+ other email MCP servers:

• Multiple accounts, one server. Work email, personal email, client accounts — all accessible through a single server. No need to run separate instances.
• Not just Gmail. Supports Gmail (full API), any IMAP/SMTP provider (ProtonMail, corporate mail, self-hosted), and JMAP (Fastmail, Stalwart, Topicbox). Add providers without changing a line of tool code.
• Built for untrusted input. Hidden-text stripping, random-nonce fences, confirmations before mail leaves the account, per-account read-only and drafts-only modes, encrypted credentials (AES-256-GCM), TLS enforcement, SSRF protection. Details in Security.
• Tools for the workflows that matter. Search, read, send, reply, forward, drafts, labels, filters, templates, signatures, vacation replies, attachments, unsubscribe, and more.
• Zero native dependencies. Pure Node.js. Install and run anywhere.

Security

Giving a model access to a mailbox means giving it access to text written by strangers. Any sender controls the subject, body, headers and attachment filenames of what the model reads, so the two risks are the model following instructions planted in an email, and the model sending mail somewhere it shouldn't (the usual goal of such instructions: forward the thread, reply with the contents of another message, mail a secret to an outside address). mailbox-mcp puts several layers between those two things.

Fenced untrusted content. Everything that came from an email is wrapped in [UNTRUSTED_ _ ] ... [/UNTRUSTED_ _ ] markers, and the server's MCP instructions tell the client that text inside them is data to report, never instructions to follow. The nonce is a random hex string chosen fresh for every tool response, so an email cannot close a fence early or open a fake one; anything in the content that even looks like a marker, in any case or with Unicode lookalike characters, has its bracket replaced before it reaches the model.

Hidden text is removed, and you're told. HTML-only messages are reduced to what a mail client would actually show. Elements hidden with display:none, visibility:hidden, opacity:0, zero or near-zero font sizes, text the same colour as its background (white on white), the hidden attribute, aria-hidden, off-screen positioning and the preheader max-height:0; overflow:hidden trick are dropped, along with comments, scripts, styles and templates. Zero-width and bidirectional control characters are stripped from every body, subject, header and filename. When anything was removed, the response ends with a visible warning saying how many characters went, so a message that says one thing to you and another to the model is flagged rather than silently cleaned.

Confirmations before mail leaves. Sending to an address the account has never sent to or received from needs confirm_new_recipient: true; the error lists the new addresses. Forwarding to a domain other than the account's own needs confirm_external_forward: true. The client is told to pass those flags only when you asked for that recipient yourself, never because an email did. Both checks are on by default.

Per-account modes. An account can carry a recipient allowlist (exact addresses and @domain patterns; everyone else is refused), a draftsOnly flag (send tools create a draft for you to review instead), and a readOnly flag (every write tool refuses; search and read keep working). These are set in accounts.json or when the account is created, and no tool can loosen them, so a hijacked session cannot switch them off. See Account safety settings.

Tool annotations. All 49 tools carry MCP readOnlyHint, destructiveHint, idempotentHint and openWorldHint annotations, so a client can auto-approve reads and always ask before anything that sends, deletes or changes settings.

Caps and a log. At most 10 sends per minute and, by default, 100 per rolling 24 hours per account; the daily count is kept on disk and survives restarts. Every send through the server is recorded in ~/.mailbox-mcp/sends.jsonl with its recipients, and every bulk label or trash operation in transactions.jsonl with an undo id.

The three options below enforce limits outside the model instead of asking it to behave. All are off by default.

Out-of-band approval ("approval": "external" per account). Every send path still runs the guards above, then writes the fully resolved message to ~/.mailbox-mcp/pending/ .json instead of sending it, and tells the model the id. No tool can list, edit or approve that queue. You do it in a terminal: mailbox-mcp pending, mailbox-mcp show , mailbox-mcp approve , mailbox-mcp reject . approve prints the whole message, reads the confirmation from /dev/tty (not stdin, so it cannot be piped), re-runs the allowlist and daily cap, reloads attachments and refuses if one changed, then sends exactly what it printed. A shell without a controlling terminal, which is what an agent's shell is, cannot open /dev/tty, so it cannot approve its own sends. Entries expire after 7 days. See Approving queued sends.

Tool profiles (MAILBOX_MCP_PROFILE). read exposes only read-only tools; draft exposes everything except the tools that can make mail leave the account or add, re-authenticate or remove accounts. Hidden tools are absent from the tool list and refuse if called anyway. See Choosing which tools load.

Lock after untrusted reads ("untrustedReadLock": "approval" | "refuse" per account). As soon as a tool shows the model a message it cannot vouch for, or exports or downloads message content to disk, the account is marked for the rest of the server process. approval then routes every send from it through the pending queue even if approval isn't set; refuse refuses sends until the server restarts. No argument the model can pass lifts it. The lock is strict by design: a message is vouched for only when its sender is on the account's trustedSenders list in accounts.json AND the receiving server's DMARC check passed for the From domain. Nothing a sender or the model can influence counts: not the From header, not the Sent folder, not the send log, not a mailbox search. With no trustedSenders configured, reading any third-party mail taints, which is the intended default; most people will want approval: "external" rather than a long trusted list. See How the lock decides.

None of this makes prompt injection impossible. A model can still be talked into a reply you didn't want, and a text/plain part can say something different from the HTML part a human sees. Keep a human approving sends. A reasonable setup: readOnly: true or MAILBOX_MCP_PROFILE=read on accounts you only need to search, approval: "external" or an allowlist on any account an agent sends from unattended, untrustedReadLock on anything that triages an inbox, and the default confirmations everywhere else.

Quick Start

Install

Add to your Claude Code MCP config (~/.claude.json). The package runs straight from npm via npx:

{

"mcpServers": { "mailbox": { "command": "npx", "args": ["-y", "mailbox-mcp"], "env": { "MAILBOX_MCP_PASSPHRASE": "a-long-random-passphrase" } } } }

MAILBOX_MCP_PASSPHRASE is the passphrase used to encrypt IMAP/JMAP credentials at rest; it's required before adding an IMAP or JMAP account, and unused for Gmail-only setups. MAILBOX_MCP_CONFIG_DIR moves the config directory somewhere other than ~/.mailbox-mcp.

From source instead

git clone https://github.com/jgalea/mailbox-mcp.git

cd mailbox-mcp npm install && npm run build

Then point the config at the build with "command": "node", "args": ["/path/to/mailbox-mcp/dist/server.js"].

Add a Gmail Account

1. Create a Google Cloud project

1. Go to Google Cloud Console and create a new project
2. Enable the Gmail API: APIs & Services > Library > Gmail API > Enable

2. Set up OAuth consent screen

1. Go to Google Auth Platform > Branding
2. Set App name and User support email
3. Go to Audience, select External
4. Add the Google account you'll sign in with as a test user (this must be the exact @gmail.com address you use to authenticate, not a workspace alias)

3. Create OAuth credentials

1. Go to Google Auth Platform > Clients > Create Client
2. Application type: Desktop app
3. Click Create
4. Go to APIs & Services > Credentials, find your client, and click the download icon to get the JSON
5. Save the file as ~/.mailbox-mcp/oauth-keys.json

4. Authenticate

In Claude Code, run: authenticate alias="personal" provider="gmail" email="you@gmail.com"

This opens a browser window to complete the OAuth flow. Your tokens are stored locally in ~/.mailbox-mcp/accounts/.

Add an IMAP Account

In Claude Code, run:

authenticate alias="work" provider="imap" email="you@company.com" host="imap.company.com" smtpHost="smtp.company.com" username="you@company.com" password="<app-password>"

Credentials are encrypted at rest using AES-256-GCM.

Add a JMAP Account

In Claude Code, run:

authenticate alias="fastmail" provider="jmap" email="you@fastmail.com" host="fastmail.com" username="you@fastmail.com" password="<app-password>"

JMAP auto-discovers the API endpoint via .well-known/jmap. Credentials are encrypted at rest using AES-256-GCM.

Supported JMAP servers: Fastmail, Stalwart, Topicbox, Cyrus IMAP, and any RFC 8620-compliant server.

JMAP advantages over IMAP:

• Native thread support (real conversations, not synthetic)
• Server-side search (faster, more accurate)
• Batch operations in a single HTTP request
• No persistent connection required

Tools

Universal (Gmail + IMAP + JMAP)

| reply_email | Reply to a message (supports from, attachments; extra cc/bcc to new ad