mailbox-mcp

<div align="center">

# mailbox-mcp

[![npm](https://img.shields.io/badge/NPM-mailbox--mcp-CB3837?style=for-the-badge&logo=npm&logoColor=white)](https://www.npmjs.com/package/mailbox-mcp)
[![License](https://img.shields.io/badge/LICENSE-MIT-5C9E31?style=for-the-badge)](LICENSE)
[![Built by](https://img.shields.io/badge/BUILT%20BY-AGENTVANIA-8A2BE2?style=for-the-badge)](https://agentvania.com)

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

</div>

mailbox-mcp is an [MCP server](https://modelcontextprotocol.io) 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](#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_<KIND>_<nonce>] ... [/UNTRUSTED_<KIND>_<nonce>]` 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](#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/<id>.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 <id>`, `mailbox-mcp approve <id>`, `mailbox-mcp reject <id>`. `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](#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. Hidden tools are absent from the tool list and refuse if called anyway. See [Choosing which tools load](#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](#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`:

```json
{
  "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`.

<details>
<summary>From source instead</summary>

```bash
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"]`.
</details>

### Add a Gmail Account

#### 1. Create a Google Cloud project

1. Go to [Google Cloud Console](https://console.cloud.google.com/) and create a new project
2. Enable the **Gmail API**: [APIs & Services > Library > Gmail API](https://console.cloud.google.com/apis/library/gmail.googleapis.com) > Enable

#### 2. Set up OAuth consent screen

1. Go to [Google Auth Platform > Branding](https://console.cloud.google.com/auth/branding)
2. Set **App name** and **User support email**
3. Go to [Audience](https://console.cloud.google.com/auth/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](https://console.cloud.google.com/auth/clients) > Create Client
2. **Application type**: Desktop app
3. Click **Create**
4. Go to [APIs & Services > Credentials](https://console.cloud.google.com/apis/credentials), find your client, and click the download icon to get the JSON
5. Save the file as `~/.mailbox-mcp/oauth-keys.json`