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.
• Security-conscious. Encrypted credentials (AES-256-GCM), prompt injection fencing on email content, rate limiting, TLS enforcement, SSRF protection with IP encoding evasion detection, input validation.
• 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.

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.

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

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

2. Set up OAuth consent screen

• Go to Google Auth Platform > Branding
• Set App name and User support email
• Go to Audience, select External
• 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

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

4. Authenticate

In Claude Code, run: authenticate alias="personal" provider="gmail" email="[e-mail]"

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="[e-mail]" host="imap.company.com" smtpHost="smtp.company.com" username="[e-mail]" 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="[e-mail]" host="fastmail.com" username="[e-mail]" 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)

Tool	Description
list_accounts	List configured accounts
authenticate	Add a new account
reauth	Re-run OAuth for an existing Gmail account (use when refresh token expires with invalid_grant)
remove_account	Remove an account
search_emails	Search messages (optional folder to scope the search)
multi_account_search	Run the same query across every configured account in parallel
read_email	Read a message
read_thread	Read a conversation thread (Gmail + JMAP)
send_email	Send a new email (supports from, attachments)
reply_email	Reply to a message (supports from, attachments)
forward_email	Forward a message (supports from, attachments)
create_draft	Create a draft (supports reply drafts via in_reply_to, plus from, attachments)
list_drafts	List drafts for an account
send_draft	Send an existing draft
trash_emails	Trash messages
mark_read	Mark a message as read or unread
star_email	Star or unstar a message
archive_email	Archive a message (remove from inbox)
list_labels	List labels/folders
create_label	Create a label/folder
delete_label	Delete a label/folder
modify_email	Modify message labels
batch_modify_emails	Bulk modify labels
bulk_modify	Add/remove labels on every message matching a query (search-then-batch; dry_run supported)
bulk_trash	Trash every message matching a query (dry_run supported)
list_recent_bulk_ops	List recorded bulk operations from the transaction log
undo_bulk_op	Reverse a recorded bulk operation against the exact ids it touched
count_unread_by_label	Show unread message counts per label/folder
download_attachment	Download an attachment
export_email	Save a message as a .eml file
export_thread	Save every message in a thread as .eml files (Gmail + JMAP)
emails_since	List messages received after a given timestamp
inbox_summary	Inbox overview

Gmail-Only

Tool	Description
update_draft	Replace the contents of an existing draft (thread association preserved)
delete_draft	Permanently delete a draft
create_filter	Create a filter
list_filters	List filters
delete_filter	Delete a filter
save_template	Save a template
list_templates	List templates
delete_template	Delete a template
send_template	Send from template
get_signature	Get signature
set_signature	Update signature
get_vacation	Get vacation settings
set_vacation	Configure vacation reply (supports date ranges, domain-only)
unsubscribe	Find unsubscribe link
bulk_unsubscribe	Bulk unsubscribe
list_send_as	List send-as aliases

Choosing which tools load

49 tool schemas cost roughly 6,000 tokens in clients that load every definition into context. In everyday use a handful of tools do most of the work, so you can expose only the groups you need with MAILBOX_MCP_TOOLS (comma-separated). Unset means everything loads.

"env": {
  "MAILBOX_MCP_TOOLS": "core,attachments"
}

Group	Tools	What it covers
core	19	accounts, search, read, send, reply, forward, drafts, inbox summary (~2,900 tokens)
organize	9	labels, star, archive, trash, modify
bulk	4	query-wide modify/trash with dry-run and undo
attachments	3	download attachments, export .eml
gmail-extras	14	filters, templates, signatures, vacation, unsubscribe, send-as

Calls to tools in disabled groups fail with an error naming the group to enable.

Sending attachments

send_email, reply_email, forward_email, and create_draft accept an optional attachments parameter — an array of local file paths. The server reads each file, detects its MIME type from the extension, and embeds it in the outgoing message (or draft).

send_email account="personal" to=["[e-mail]"] subject="The report" body="See attached." attachments=["/path/to/report.pdf", "/path/to/chart.png"]

• Each file must be a regular file ≤ 25 MB; total per message is capped at 25 MB (Gmail's hard limit).
• Paths are resolved through any symlinks, and filenames are stripped of CRLF before going into headers.
• Gmail routes messages with attachments through the multipart upload endpoint (35 MB API limit) instead of the JSON endpoint, so the 25 MB message cap is the real ceiling.
• JMAP uploads each file to the server's upload URL first, then references the resulting blobIds in the Email/set call.

Choosing the sender address

One account often speaks for several addresses. send_email, reply_email, forward_email, create_draft, and update_draft accept an optional from parameter; without it, the account's primary address is used.

reply_email account="personal" message_id="18f..." from="[e-mail]" body="Thanks, sorted."

Accepted forms are [e-mail] and Name <[e-mail]>; matching is case-insensitive.

The address is checked against the account before anything is sent, and the call fails with the list of usable addresses if it doesn't match. This matters because Gmail silently falls back to the primary address when the From header names an address you haven't verified, so a message can be sent from the wrong identity and still look like it succeeded. Some recipients (Amazon's customer service, for one) reject mail that doesn't come from the address on file.

• Gmail: the address must be a send-as alias with verification completed. Run list_send_as to see them. Pending aliases are refused.
• JMAP: the address must match one of the account's identities; its identityId is attached to the submission.
• IMAP: no alias list exists to check against, so any from is passed to the SMTP relay, which accepts or rejects it at send time.

License

MIT

Built at AgentVania.