Mailbox — MCP server for Claude Code: IMAP/SMTP mail for your agent
Connects an agent to mail accounts over IMAP and SMTP: read, file away, prepare drafts, send. Permissions are tied to bearer tokens.
Open on GitHubWhat Mailbox does
The service runs in Docker and serves an HTTP API plus an MCP endpoint at /mcp on one port. Several accounts can sit behind it, each described in config.yaml. Message bodies and drafts never leave IMAP. A local SQLite file holds operational records only: audit entries, send counters, checkpoints and webhook delivery metadata.
Tokens decide what the agent can do. Give a token read, draft and organize and it will not even see send or delete tools. A delete moves the message to Trash; wiping it for good requires the delete scope and works only inside Trash, and the service never runs a folder-wide EXPUNGE. Drafts are a two-step affair: the agent writes one, a person or a token holding send releases it. Sending also passes an hourly rate limit, an optional dry-run and a check that the sender address matches a configured identity.
Before the first start you need config.yaml and .env. Put passwords or freshly generated tokens from openssl rand -hex 32 there, then run chmod 600 on both files and mount the config read-only. Mount a volume at /var/lib/mailboxd too, otherwise audit records and counters vanish on restart. The stack is Python: imaplib, smtplib, FastAPI, the official MCP Python SDK and nh3 for sanitizing HTML.
What it helps with
- pull the latest messages from a shared inbox into an agent
- file incoming mail into folders and labels
- prepare a reply draft for a colleague to approve
- send mail from a verified sender within a rate limit
- inspect SPF, DKIM and DMARC verdicts on a suspicious message
Example prompts for the agent
- Show me the five newest inbox messages and summarize them.
- Find this week's mail from the finance team and move it to the
financefolder. - Draft a reply to the latest client message, don't send it yet.
How to install Mailbox
Install
The MCP registry has no launch command for it: see the repository README
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
How do I install Mailbox for Claude Code?
There is no ready install command. Copy config.example.yaml to config.yaml and .env.example to .env, fill in accounts and tokens, then start the container: `docker run --rm -p 127.0.0.1:8000:8000 --env-file .env -v "$PWD/config.yaml:/etc/mailboxd/config.yaml:ro" -v mailboxd-state:/var/lib/mailboxd psyb0t/mailbox:latest. Point the agent at the /mcp` endpoint afterward.
What does Mailbox do?
It sits between an agent and mail accounts: lists and searches messages, moves them between folders, prepares drafts and sends them. Both the HTTP API and the MCP endpoint honor the same token scopes.
Can I give the agent read-only access?
Yes. A token without draft, organize, send and delete sees only the reading tools. Sending is separately capped by an hourly limit and restricted to configured sender identities.
