Classic Mail

A self-hosted MCP server for the IMAP and SMTP mailbox you already have. Connect an AI assistant to search and read email, inspect attachments, and — when explicitly enabled — send messages, manage drafts and organize folders.

Built for people whose mail provider does not offer an AI integration. Run it on your computer with Docker, on your own server, or on Google Cloud Run. Every installation belongs to one operator, with up to ten configured mailboxes.

Public preview. Automated tests cover the protocol and security boundaries; provider compatibility and client sign-in must still be verified on your installation. This project has not had an independent security audit.

What it does

Six tools are available by default; all 21 tools become available with ACCESS_MODE=read-write. Complete tool reference →

• TLS certificate validation for every mailbox connection.

• IMAP 993 / SMTP 465 with implicit TLS; IMAP 143 / SMTP 587 with mandatory STARTTLS.

• OAuth with Google sign-in for remote clients; bearer authentication for local HTTP; stdio for local MCP clients.

• Persistent send history prevents automatic duplicate submissions when the same idempotency key is retried.

• No mailbox passwords, bearer tokens or mail bodies in application logs.

• SQLite with persistent disk locally; Firestore for multiple Cloud Run instances.

Related MCP server: IMAP MCP Server

Choose a connection

Google sign-in authenticates you to this MCP. It does not grant Gmail access. Your configured IMAP/SMTP credentials authenticate to your mail provider separately.

Quick start: local Docker

Requirements: Docker with Compose, Python 3 for the private setup wizard, and an IMAP/SMTP account that permits password or app-password authentication.

git clone https://github.com/kapitelh/classic-mail-mcp.git
cd classic-mail-mcp
python3 scripts/setup.py
docker compose up --build -d

The wizard hides passwords and generates independent random keys. It creates .secrets/config.json, .data/ and .env. These are excluded from Git and Docker builds. The default Compose service binds only to 127.0.0.1:8080.

Open the local service page. In your MCP client, use:

If your client asks for a bearer-token environment variable, enter a variable name such as CLASSIC_MAIL_TOKEN, not the token itself. Set that variable in the environment used to launch your client. A GUI app may not inherit variables from your terminal. The Google OAuth client secret is never a bearer token. Client examples →

Then ask your agent:

1. “List the accounts available through Classic Mail.”

2. “Check the connection for account mail1.”

3. “Show the latest five messages in INBOX without marking them as read.”

A healthy service page is not proof of a working mailbox. These checks verify discovery, credentials and an actual read.

Enable sending and management

Set ACCESS_MODE=read-write in .env, then:

docker compose up -d

Refresh the tool list in your client. Configure the client to request confirmation for sending and destructive operations. Server descriptions cannot enforce a human approval dialog in arbitrary clients. All connected clients for this operator share access to the same configured accounts.

Local stdio

Use the same private configuration or run the wizard with --mode stdio. Build once:

docker build -t classic-mail-mcp:local .

Configure your MCP client to launch the Docker command documented in client setup. Use -i, never -t, and mount both configuration and persistent data. No HTTP port is exposed in stdio mode.

Deploy with OAuth

Deployment guide → covers a persistent Docker host with an HTTPS reverse proxy and a two-stage Google Cloud Run setup script. You need your own cloud project, Google OAuth web client, credentials and allowed sign-in identity. There is no shared hosted mailbox service.

Provider support

Any provider with standard IMAP/SMTP password or app-password authentication and a valid TLS certificate can be configured. Credentials may have a separate SMTP username/password. Hostnames are supplied by the operator, not by tools.

The automated suite uses synthetic IMAP, SMTP and OAuth responses. It does not certify individual providers. Accounts requiring provider OAuth/XOAUTH2 (for example some Microsoft or Google configurations), local plaintext mail bridges, custom ports and enterprise SSO are not implemented. Check your provider's current requirements before installing.

Limits you should know

• Messages up to 8 MiB use full MIME parsing. Larger messages read individual text parts without loading their attachments; a shared 8 MiB decoded body budget still applies (bodyLimited).

• Text is returned in 50,000-character pages. Pass nextTextOffset as textOffset until it is null. Empty plain-text alternatives fall back to HTML-to-text conversion.

• Attachments download in 128 KiB chunks, up to 128 MiB decoded / 192 MiB encoded. Follow nextOffset. For large messages, decoded size is null until the final chunk; encodedSize is a separate wire-size value. Large-part retries may re-read the prefix, but only the requested chunk is retained in memory.

• Sending, draft creation and forwarding still have an 8 MiB message limit. Text extraction is not OCR and does not decrypt S/MIME or PGP.

• A search page scans at most 10,000 UIDs. Follow nextBeforeUid even if a page is empty.

• Folder restrictions are exact matches. Special folders may need explicit configuration.

• SMTP acceptance is not recipient delivery. Sent-folder copying can fail separately.

• Never retry an uncertain send with a new idempotency key. Inspect the provider's Sent folder first.

• The server connects to existing mailboxes; it does not host incoming SMTP, run a background inbox watcher or provide push notifications.

• No multi-user isolation: run a separate instance and storage for each person.

Development

Node.js 24, npm, Python 3 and OpenSSL are used by the checks.

npm ci
npm run check
docker build -t classic-mail-mcp:local .

See configuration, architecture, troubleshooting, contributing and security reporting.

Made by kapitelh. Released under the MIT license.