mailbox
Provides email integration for Gmail accounts, enabling unified inbox access, searching, reading, sending, and deleting emails via IMAP and SMTP.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
mailbox
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
Related MCP server: @marlinjai/email-mcp
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:latestCheck 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' | jqDocker 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 |
Docker, Compose, the webhook watcher, image tags, CLI and environment variables | |
Every config field: mailboxes, tokens and scopes, identities, limits, labels | |
Routes, parameters, bodies, responses and error codes | |
Tools, scopes, annotations and client setup | |
Deletion, drafts, dry runs, rate limits, sender checks, audit, TLS | |
Event payload, signature verification, retries and replay | |
Claude Code, Codex and OpenClaw | |
State, backups, health checks and upgrade notes | |
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 targetsAll 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
Copyright (C) 2026 Ciprian Mandache. Licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only). If you run a modified version as a network service, you must offer its source to the people who use it. Releases up to 0.8.2 were published under the WTFPL and keep it. See third-party components. The OpenClaw plugin in .agents/plugins/mailbox is MIT.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Hosted email MCP for your own Gmail, Outlook.com, Microsoft 365, iCloud or IMAP inbox: read, search, draft, reply in thread, forward and file mail. It moves or flags up to 500 messages in one call, and a send leaves exactly one copy in Sent. A calendar is a separate connection, and connecting one adds diary and scheduling tools.
Hosted MCP server for your Gmail, Outlook and IMAP mail, with mailboxes and scopes set per agent.
Your own IMAP mailbox in any MCP client: search, read, flag, move; send and delete need confirm.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA comprehensive MCP server for unified email management that supports both Gmail and IMAP accounts via a single interface. It enables users to search across multiple accounts, list, read, send, and archive emails with integrated health monitoring and secure authentication.1MIT
- AlicenseBqualityBmaintenanceA unified MCP server for email access across Gmail, Outlook, iCloud, and generic IMAP providers, enabling search, send, organize, and batch operations.36208 npm26MIT
- AlicenseAqualityDmaintenanceMCP server that enables email management (send, read, search, delete, etc.) via IMAP/SMTP, compatible with Gmail, Outlook, Yahoo, iCloud, and other standard mail servers.11MIT
- AlicenseNot gradedqualityBmaintenanceEnables remote email management for Gmail, Outlook, iCloud, Yahoo, and custom IMAP/SMTP accounts via MCP, supporting account setup, search, read, draft, and send operations.MIT