Scoped IMAP/SMTP access over HTTP and MCP: read, organize, draft, reply and send mail.
io.github.psyb0t/mailbox MCP Server
Self-hosted Model Context Protocol (MCP) server for unified IMAP/SMTP mailbox access. It supports reading, listing, and sending email, using a mailbox-focused approach to provide an inbox interface for tools.
🛠️ Key Features
Unified IMAP/SMTP mailbox access
Read and list emails
Send email
🚀 Use Cases
Access a self-hosted inbox via MCP
Use email operations (read/list/send) from LLM tools
⚡ Developer Benefits
Runs as a self-hosted MCP server
Integrates with MCP and LLM tools workflows
Container-friendly: Docker-related configuration is referenced
⚠️ Limitations
Limited details provided beyond read, list, and send email over IMAP/SMTP
Additional setup and configuration details are not included in the available excerpt
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, draft and organize cannot send or permanently delete. Over MCP it does not even see the send tools or the permanent flag.
Deletion defaults to Trash. Deleting moves a message to Trash. Permanent erasure needs the delete scope and only works from the Trash folder. The service never issues a folder-wide EXPUNGE.
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.
Copy config.example.yaml to config.yaml and .env.example to .env. Configure your accounts and replace every placeholder in .env with its password or a fresh token from openssl rand -hex 32. Restrict both files with chmod 600.
Start the container. The named volume preserves operational state across restarts:
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:
yaml
services:mailboxd:image:psyb0t/mailbox:latestports: ["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/mailboxdvolumes: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.
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.