Mailbox MCP server
Commit Nov 10, 2026Allows an AI client to read, organize, draft, and send emails across multiple IMAP/SMTP accounts via a scoped HTTP API and MCP endpoint.
Also known as psyb0t/docker-mailbox, docker-mailbox
- Stars
- 9
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.8.2
- Last commit
- Nov 10, 2026
- License
- WTFPL
What is Mailbox MCP?
Mailbox allows an AI client to read, organize, draft, and send emails across multiple IMAP/SMTP accounts via a scoped HTTP API and MCP endpoint.
Summary generated from the project's README
About Mailbox MCP server
Mailbox provides a way for AI agents to interact with multiple IMAP and SMTP email accounts through a single interface. It functions as both a scoped HTTP API and an MCP endpoint located at /mcp. Developers can deploy this service using Docker, configuring it with a YAML file and environment variables to manage different mailboxes and identities. The system is designed for security, using bearer tokens to restrict what an agent can do, such as limiting access to reading, drafting, or organizing without allowing permanent deletion or sending.
This server manages email operations like searching threads, inspecting headers, and handling attachments. It includes safety features like an hourly rate limit for sending, a dry-run mode, and automated message analysis to check SPF, DKIM, and DMARC verdicts. While mail bodies and drafts remain on the IMAP server, the service uses a local SQLite database to maintain audit logs, send counters, and webhook metadata. This setup ensures that an AI client can assist with email management while maintaining strict operational boundaries.
What you can do with it
- 1Drafting email repliesAn AI agent can prepare a response to an incoming message and save it as a draft for a human to review.
- 2Analyzing email securityA developer can use the tool to inspect email headers and authentication verdicts to detect deceptive links or mismatches.
- 3Restricting agent permissionsYou can create a token that allows an agent to read and organize mail without giving it the ability to send messages.
Written from the project's README. Every use case is checked against a quote from it.
How to install Mailbox MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Mailbox MCP in Claude Code
$ claude mcp add docker-mailbox -- docker run -i --rm docker.io/psyb0t/mailbox:v0.8.2Install Mailbox MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"docker-mailbox": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/psyb0t/mailbox:v0.8.2"
]
}
}
}Install Mailbox MCP in VS Code
.vscode/mcp.json
{
"servers": {
"docker-mailbox": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/psyb0t/mailbox:v0.8.2"
]
}
}
}Install Mailbox MCP in VS Code CLI
$ code --add-mcp '{"name":"docker-mailbox","type":"stdio","command":"docker","args":["run","-i","--rm","docker.io/psyb0t/mailbox:v0.8.2"]}'Install Mailbox MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"docker-mailbox": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/psyb0t/mailbox:v0.8.2"
]
}
}
}Install Mailbox MCP in Codex
$ codex mcp add docker-mailbox -- docker run -i --rm docker.io/psyb0t/mailbox:v0.8.2Install Mailbox MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.docker-mailbox] command = "docker" args = ["run", "-i", "--rm", "docker.io/psyb0t/mailbox:v0.8.2"]
Install Mailbox MCP in Gemini CLI
$ gemini mcp add -s user docker-mailbox docker -- run -i --rm docker.io/psyb0t/mailbox:v0.8.2Install Mailbox MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"docker-mailbox": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/psyb0t/mailbox:v0.8.2"
]
}
}
}Automated checks
Ran Nov 13, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablePass
- Open source license (OSI)WTFPL is not OSI-approvedFinding
- Commit or release in the last yearPass
- Package name not close to a popular packageNot checked
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubmailbox
Read, organize, draft and send mail across multiple IMAP/SMTP accounts through one HTTP API and an MCP endpoint at /mcp, on the same port. Each bearer token controls which operations and mailboxes a client can access.
For agent access, configure tokens with explicit permissions:
- Scoped tokens. A token that holds
read,draftandorganizecannot send or permanently delete. Over MCP it does not even see the send tools or thepermanentflag. - Deletion defaults to Trash. Deleting moves a message to Trash. Permanent erasure needs the
deletescope and only works from the Trash folder. The service never issues a folder-wideEXPUNGE. - Drafts in two steps. An agent can prepare a reply; a human (or a token with
send) sends it. - Send guard. Hourly rate limit, dry-run mode, and a sender address authorized by your configured exact identities or opt-in domain patterns.
- Message analysis. Inspect SPF/DKIM/DMARC verdicts, header mismatches, hidden text and deceptive links. Verdicts are trusted only when the receiving server matches your configuration. Request sanitized HTML when needed.
- Audit log. Writes are recorded, including those refused for a missing scope or rejected by the mail server. Message bodies never are.
Mail bodies and drafts stay on IMAP. A shared SQLite database stores audit records, send counters, checkpoints, draft send claims and webhook delivery metadata. API requests close their mail-server connections after use; the watcher keeps an IMAP connection open for notifications.
The service uses Python's imaplib and smtplib, FastAPI, the official MCP Python SDK and nh3 for HTML sanitizing. Dependency updates enforce a seven-day release-age cutoff through uv's exclude-newer setting.
Contents
Quick start
- Copy
config.example.yamltoconfig.yamland.env.exampleto.env. Configure your accounts and replace every placeholder in.envwith its password or a fresh token fromopenssl rand -hex 32. Restrict both files withchmod 600. - Start the container. The named volume preserves operational state across restarts:
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
- Check health and list mail:
TOKEN="paste-the-token-here"
# Health is always open, no token needed.
curl -s http://localhost:8000/health | jq
curl -s \
-H "Authorization: Bearer $TOKEN" \
http://localhost:8000/mailboxes | jq
curl -s \
-H "Authorization: Bearer $TOKEN" \
'http://localhost:8000/inbox?limit=5' | jq
Docker Compose
The checked-in docker-compose.yml publishes on 127.0.0.1:${PORT:-8000}, mounts ./config.yaml (or $MAILBOXD_CONFIG) read-only and creates the mailboxd-state volume:
services:
mailboxd:
image: psyb0t/mailbox:latest
ports: ["127.0.0.1:8000:8000"]
volumes:
# Keep config.yaml out of Git and restrict access to its credentials.
- ./config.yaml:/etc/mailboxd/config.yaml:ro
- mailboxd-state:/var/lib/mailboxd
volumes:
mailboxd-state:
The optional webhook watcher is a second service in the same file, off by default: docker compose --profile watch up -d.
Capabilities
| Area | Operations |
|---|---|
| Reading | Unified inbox, structured search, raw source, headers, attachments and threads |
| Organization | Seen flags, labels, move, mailbox creation and Trash |
| Sending | Configured identities, signatures, replies, IMAP drafts and Sent copies |
| Access | Per-token scopes and mailbox allowlists shared by REST and MCP |
| Operations | SQLite audit records, shared send limits, checkpoints and durable signed webhooks |
Mount /var/lib/mailboxd for persistent operational state. HTTP workers and the optional watcher share one SQLite database on a local filesystem. Read the upgrade notes before replacing a stateless deployment.
Documentation
The full documentation lives at psyb0t.github.io/docker-mailbox.
| Page | What is in it |
|---|---|
| Installation | Docker, Compose, the webhook watcher, image tags, CLI and environment variables |
| Configuration | Every config field: mailboxes, tokens and scopes, identities, limits, labels |
| HTTP API | Routes, parameters, bodies, responses and error codes |
| MCP server | Tools, scopes, annotations and client setup |
| Safety and security | Deletion, drafts, dry runs, rate limits, sender checks, audit, TLS |
| Webhooks | Event payload, signature verification, retries and replay |
| Agent integrations | Claude Code, Codex and OpenClaw |
| Operations | State, backups, health checks and upgrade notes |
| Troubleshooting | Startup errors and common API failures |
Development
make lint # flake8 and mypy
make test-coverage # full suite, production container and coverage floor
make audit # frozen runtime and dev dependency advisories
make build # production image
make help # all available targets
All project tools run inside the development image. Tests use socket-level IMAP/SMTP fixtures, a local HTTP receiver, real SQLite files and a production-container smoke test. See development for details.
Sponsor
License
WTFPL. See LICENSE and third-party components.
Mailbox MCP questions
How do I add Mailbox MCP to Claude Code?
Run claude mcp add docker-mailbox -- docker run -i --rm docker.io/psyb0t/mailbox:v0.8.2 in your terminal. Add --scope user to make it available in every project.
How do I add Mailbox MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How does the server handle email deletion?
Deleting a message moves it to the Trash folder by default. Permanent erasure requires the 'delete' scope and can only be performed from the Trash folder.
Can an AI agent send emails directly?
Agents can prepare replies as drafts, but sending requires a token with 'send' permissions or human intervention.
What security measures are in place for sending mail?
The service includes an hourly rate limit, a dry-run mode, and requires sender addresses to match authorized identities or domain patterns.
Does the service store email bodies in the audit log?
No, while writes and refused operations are recorded in the audit log, message bodies are never stored there.