mailbox-mcp-server
Connects to cPanel-hosted email accounts over IMAP/SMTP, enabling users to read, search, send, and organize their mailbox messages and folders.
Integrates with Dovecot IMAP/SMTP mail servers to provide email reading, searching, sending, and mailbox organization capabilities.
Connects to Gmail over IMAP/SMTP using an app password, allowing users to read, search, send, and organize Gmail messages from the assistant.
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-mcp-server
A remote MCP server that connects AI assistants such as Claude to email over plain IMAP/SMTP.
Each user adds one URL as a connector, signs in with their own mailbox email and password, and can then read, search, send and organise their mail from the assistant. It works with Mailcow, Dovecot/Postfix, cPanel mail, Gmail (app password) and any standard mail server.
Claude ──HTTPS──▶ reverse proxy ──▶ mailbox-mcp-server :3900 ──IMAP/SMTP──▶ your mail server
│
└─ sign-in page: email + password, checked by an IMAP loginTo administer a Mailcow server (domains, mailboxes, aliases, queue, DKIM, ...) from Claude, see the companion project mailcow-mcp-server.
Features
Per-user sign-in. OAuth 2.1 with dynamic client registration and PKCE. The connector opens a sign-in page, and the password is verified by logging in to your IMAP server.
Isolated mailboxes. Every signed-in user sees and sends only from their own mailbox.
Encrypted at rest. Saved sign-ins are AES-256-GCM encrypted. Access tokens are stored only as SHA-256 hashes and expire after 90 days.
Brute-force protection. 5 failed sign-ins per IP address lock that IP out for 10 minutes. You can restrict sign-in to one domain.
Owner mode (optional). Fixed accounts (for example a work mailbox and Gmail) can be reached with a static bearer token.
Stateless Streamable HTTP transport, with a Docker image, healthcheck and Compose file included.
Related MCP server: email-mcp
Tools
Tool | What it does |
| Unread and total message counts per folder |
| List mail folders |
| Recent emails in a folder (newest first) |
| Search by sender, subject, body text or date |
| Full content of one email, with an attachment list |
| Send a new email or a reply ( |
| Mark as read/unread, flagged/unflagged |
| Move an email to another folder |
| Move to Trash, or delete permanently |
| Create a folder |
Quick start (Docker)
git clone https://github.com/mustafa-mph/mailbox-mcp-server.git
cd mailbox-mcp-server
cp .env.example .env
# edit .env: PUBLIC_BASE_URL, SESSION_SECRET (openssl rand -hex 32), USER_IMAP_HOST, ...
docker compose up -d --build
curl http://127.0.0.1:3900/healthz # -> okReverse proxy (HTTPS is required)
MCP clients only connect over HTTPS. Here is an example for Caddy, which gets the certificate automatically:
mcp.example.com {
encode zstd gzip
reverse_proxy 127.0.0.1:3900
}For Nginx, proxy https://mcp.example.com to http://127.0.0.1:3900 and pass X-Forwarded-For. Set PUBLIC_BASE_URL=https://mcp.example.com.
Without Docker
npm install
cp .env.example .env # and edit it
SESSION_FILE=./data/sessions.json npm startRequires Node.js 20 or newer.
Connect it to Claude
In Claude, open Settings → Connectors → Add custom connector.
Enter your server URL, e.g.
https://mcp.example.com.Click Connect. The sign-in page opens.
Enter your mailbox email and password.
Ask Claude something like "show my unread emails from today".
Configuration
All settings are environment variables, usually set in .env. See .env.example for the full list.
Variable | Required | Description |
| yes | Public HTTPS URL of this server |
| yes | 32+ random characters; encrypts saved sign-ins |
| for sign-in | IMAP server used to check passwords and read mail |
| for sign-in | SMTP server for sending (defaults to the IMAP host) |
| Default | |
| Allow only | |
| Name shown on the sign-in page | |
| Comma list of fixed accounts, e.g. | |
| with owner accounts | Static bearer token for the owner accounts |
| Settings for each owner account | |
| Number of reverse proxies in front of the server (default |
Security notes
Passwords are stored by necessity. IMAP and SMTP need the password on every connection, so the server keeps it encrypted with
SESSION_SECRET. Protect.envanddata/. Anyone with both can decrypt the saved passwords.Signing everyone out. Change
SESSION_SECRET, or deletedata/sessions.json, then restart.Expiry. A sign-in expires after 90 days, and the user then signs in again.
Only run it behind HTTPS. The sign-in page sends the password to this server.
Logs. The request log records only the method, path and status code. Tokens and headers are never logged.
Gmail. Gmail requires an App Password when 2-step verification is on.
Development
index.js MCP server, mail tools, HTTP transport, auth routing
oauth.js OAuth endpoints, sign-in page, encrypted session storeIssues and pull requests are welcome.
License
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
Connect any mailbox to Claude, ChatGPT & AI: read, send, reply, schedule & search emails.
Your mailboxes in ChatGPT and Claude: Gmail, iCloud, Fastmail, any IMAP. Passwords stay yours.
Connect any IMAP/SMTP mailbox to Claude & ChatGPT: search, read, sort, draft. Sends only with OK.
Gmail, Outlook, iCloud, Fastmail and any IMAP mailbox for your agent. Scoped OAuth, approved sends.
Related MCP Servers
- AlicenseAqualityAmaintenanceEnables Claude to interact with email accounts via IMAP and SMTP, providing tools for searching, reading, sending, and managing emails across multiple providers.40931 npm130MIT
- FlicenseNot gradedqualityBmaintenanceEnables Claude to read, search, draft, send, flag, and move email across multiple IMAP/SMTP mailboxes while keeping credentials local.-
- AlicenseNot gradedqualityBmaintenanceEnables Claude and ChatGPT to read, search, and organize mail in a user's own email account, including folders, threads, attachments, drafts, and optional sending, with per-user permission levels and OAuth-secured remote connections.MIT
- AlicenseAqualityBmaintenanceEnables Claude to connect unlimited Gmail and IMAP mailboxes, search and triage them together while identifying each account, read attachments, and create drafts or perform permitted mailbox actions under configurable safety modes.2355 npm1MIT