Log inSubmit server
Mailbox MCP logo

Mailbox MCP

Manage Gmail, IMAP, and JMAP accounts with MCP tools for email search, reading, sending, drafts, labels, and bulk actions.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Mailbox MCP

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "mailbox-mcp-2": {
      "command": "npx",
      "args": [
        "-y",
        "mailbox-mcp"
      ],
      "env": {
        "MAILBOX_MCP_PASSPHRASE": "YOUR_VALUE_HERE",
        "MAILBOX_MCP_CONFIG_DIR": "YOUR_VALUE_HERE",
        "MAILBOX_MCP_PROFILE": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

We couldn’t confirm it starts correctly

We ran the install command but it didn't respond within our test window — this can mean a slow first-time install rather than a real problem.

npx -y mailbox-mcp

No response to initialize.

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked 9d ago.

Overview

The mailbox-mcp MCP server connects AI clients to Gmail, IMAP/SMTP providers, and JMAP mail services through one multi-account interface. It supports searching, reading, sending, replying, forwarding, drafting, labeling, archiving, attachments, and controlled bulk operations. Use it when an agent needs mailbox access across personal, work, or client accounts, with account-level read-only and drafts-only controls. It runs through npm or a local Node.js build and stores non-Gmail credentials encrypted at rest.

Use cases

  • Search messages across work and personal accounts
  • Draft replies with attachments for human review
  • Triage inboxes with labels and unread counts
  • Run reversible bulk label or trash operations
  • Export messages and download attachments

Key features

  • Multi-account Gmail, IMAP, and JMAP access
  • Cross-account email search
  • Send, reply, forward, and draft workflows
  • Labels, folders, archive, star, and trash controls
  • Dry-run bulk actions with undo records
  • Account-level sending and reading restrictions

Tools49

What Mailbox MCP lets your agent do. Expand a tool for its parameters.

Self-reported~623 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 3d ago

Recent health check succeeded.

7/7 checks healthy over the last 41d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 13d ago via OSV.dev · mailbox-mcp (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars10Stargazers on the source repository.
npm downloads951Package downloads in the last 30 days.
Last commit11d agoMost recent push to the default branch.
Install checkInconclusiveDidn't respond in our test window — often a slow first install.
Tools exposed49Callable tools this server registers over MCP.
Directory activity3 viewsConfig copies, upvotes, and views on AllMCPs.

How Mailbox MCP works

What mailbox-mcp does

The mailbox-mcp MCP server gives an MCP-compatible AI client access to multiple email accounts from one process. It supports Gmail, generic IMAP/SMTP providers, and JMAP services. This covers hosted and self-managed mail systems, including providers that expose IMAP or JMAP rather than a Gmail API.

Read operations include account listing, message search, cross-account search, message and thread retrieval, draft listing, label or folder listing, unread counts, attachment downloads, and .eml export. Write operations include sending, replying, forwarding, creating and sending drafts, trashing messages, changing read state, starring, archiving, and modifying labels.

Bulk tools can apply label changes or trash messages selected by a search query. These operations support dry runs, and recorded bulk operations can be reviewed and undone against the exact message IDs they changed.

How it works

The mailbox-mcp MCP server is launched as an MCP process, commonly with npx -y mailbox-mcp, and communicates with the configured client over the client’s MCP connection. Accounts are added through the authenticate tool. Gmail accounts use OAuth, while IMAP and JMAP credentials are protected with an encryption passphrase.

A single server can expose several accounts. multi_account_search runs one query across all configured accounts in parallel, while other tools accept an account context for targeted operations. Gmail and JMAP support conversation-thread reading; message search can optionally be limited to a folder.

The server includes safeguards for untrusted email content. Returned mail content is fenced and hidden HTML content, scripts, comments, tracking-style hidden text, and certain control characters are removed. Sending to a new recipient or forwarding outside the account’s domain requires an explicit confirmation flag by default. Per-account read-only, drafts-only, recipient allowlist, approval, and untrusted-read-lock settings provide additional control.

Setup and configuration

For an npm installation, configure the MCP client to run npx with mailbox-mcp as its package argument. Set MAILBOX_MCP_PASSPHRASE when adding IMAP or JMAP accounts; it encrypts those credentials at rest and is not used for Gmail-only setups. MAILBOX_MCP_CONFIG_DIR can relocate the default ~/.mailbox-mcp configuration directory.

A source installation can be built with npm and started by pointing the MCP configuration at dist/server.js. Gmail account setup requires a Google Cloud project and OAuth. Existing Gmail accounts can be reauthenticated with reauth if the refresh token fails with invalid_grant.

The MAILBOX_MCP_PROFILE variable can restrict the loaded tool set. The read profile exposes read-only tools, while draft excludes tools that send mail from an account. The profile does not replace per-account safety settings.

Tools and capabilities

The mailbox-mcp MCP server exposes tools for:

  • Listing, adding, reauthenticating, and removing accounts
  • Searching one or all accounts, then reading messages or threads
  • Sending, replying, forwarding, drafting, and sending saved drafts
  • Listing, creating, deleting, and changing labels or folders
  • Marking mail read or unread, starring, archiving, and trashing messages
  • Downloading attachments and exporting messages as .eml files
  • Running dry-run bulk label or trash operations
  • Reviewing and undoing recorded bulk operations
  • Counting unread messages by label or folder

Send, reply, forward, and draft operations support a selected sender and attachments. Reply drafts can reference the original message with in_reply_to.

Limitations and notes

Gmail, IMAP/SMTP, and JMAP do not necessarily provide identical behavior, so some capabilities vary by provider. Thread reading is specifically supported for Gmail and JMAP. Gmail OAuth must be re-run when an account’s refresh token becomes invalid.

The server’s protections reduce the risk of prompt injection but do not make unwanted replies or sends impossible. Sending is rate-limited, and sends plus bulk operations are recorded on disk. External approval can queue messages for terminal approval, but the approval step requires a controlling terminal and cannot be performed by an agent’s shell alone.

Accounts configured as read-only reject write tools, and drafts-only accounts turn send paths into drafts for review. Bulk changes and trashing should still be reviewed carefully, even when using dry-run mode.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Mailbox MCP

mailbox-mcp is an MCP server that connects AI clients to Gmail, IMAP/SMTP providers, and JMAP services. Its main tools search and read messages, manage threads and drafts, send or reply to email, handle labels, download attachments, and run controlled bulk operations across multiple configured accounts.

Install it by configuring your MCP client to run `npx -y mailbox-mcp`. You can also clone the repository, run `npm install && npm run build`, and start `dist/server.js` with Node. Set the passphrase before adding IMAP or JMAP accounts.

Yes, mailbox-mcp works with Cursor. The README also names Claude Code and Windsurf as supported AI clients. Configure the client to launch the package with `npx`, or point it to a locally built `dist/server.js`.

Run the `reauth` tool for the existing Gmail account when its refresh token expires with `invalid_grant`. The tool starts the OAuth flow again without requiring you to remove the account first.

Use an account-level `readOnly` setting or set `MAILBOX_MCP_PROFILE=read`. The account setting rejects write tools for that account, while the read profile exposes only read-only tools for the server process.

Related MCP servers

All in Communication All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewMailbox MCP AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/mailbox-mcp-2?style=directory)](https://allmcps.com/mcp/mailbox-mcp-2)
HTML Embed
<a href="https://allmcps.com/mcp/mailbox-mcp-2"><img src="https://allmcps.com/api/badge/mailbox-mcp-2?style=directory" alt="Mailbox MCP on AllMCPs" /></a>