imap-mcp

imap-mcp exposes one IMAP mailbox as seven MCP tools over Streamable HTTP. Read tools work once IMAP is configured. Sending, draft creation, and trash moves stay off until you enable each capability.

The server uses standard IMAP and SMTP settings. It does not select a mail provider or endpoint for you.

What it exposes

mail_trash uses IMAP MOVE. It does not delete or expunge messages. Send/draft and trash operations have separate rate limits.

Related MCP server: simple-email-mcp

Requirements

• Node.js 22.9 or newer

• An IMAP account

• An SMTP account if you enable sending

• TLS in front of the HTTP endpoint when it is reachable over a network

Quick start

cp .env.example .env
openssl rand -base64 32
npm ci
npm run build
npm start

Put the generated token in MCP_AUTH_TOKEN, then fill in the IMAP values in .env. The server listens on 127.0.0.1:3000 by default and accepts MCP requests at POST /mcp.

Clients must send the token as a bearer:

Authorization: Bearer <MCP_AUTH_TOKEN>

examples/mcp.json contains a client configuration with placeholder values.

Configuration

Core settings

Send and draft settings

Trash settings

Runtime boundaries

MCP client
    │  HTTPS + bearer token
    ▼
TLS reverse proxy
    │  POST /mcp
    ▼
HTTP transport → MCP adapter → MailAccount
                                ├─ IMAP: read, draft, move
                                └─ SMTP: send

MailAccount owns capability checks and rate limits. The MCP layer validates tool input and maps domain errors. IMAP and SMTP adapters contain provider protocol details. See CONTEXT.md for the domain terms used in the code.

Deployment is intentionally outside this repository. The tracked project contains no service unit, tunnel configuration, private hostname, or provider-specific endpoint.

Security notes

• Keep the default loopback bind unless a trusted reverse proxy handles TLS and access control.

• Treat the bearer token as mailbox access. Rotate it after suspected exposure.

• Keep ALLOW_SEND and ALLOW_TRASH disabled unless the connected client should mutate the mailbox.

• Store credentials in the runtime environment. Do not add .env or client tokens to the repository.

• Application logs record operation names, status, latency, and provider error messages. They do not intentionally log message subjects or bodies.

• mail_get downloads at most 10 MB per message for parsing. It never returns attachment contents.

Prompt injection in an email can influence an MCP client or agent that reads it. The server limits mutation scope and frequency, but the client remains responsible for deciding when a tool call is appropriate.

Report vulnerabilities through the process in SECURITY.md.

Development

npm ci
npm run typecheck
npm run build
npm test

The default suite uses fake mail adapters and does not need mailbox credentials or external network access. Provide .env only when you want the read-only IMAP integration check:

npm run test:integration

The integration check connects to the configured account and searches for at most one message. It does not send, draft, move, or delete mail.

Read CONTRIBUTING.md before opening a pull request.

Known limits

• One server process handles one mailbox account.

• UIDs belong to one folder and UIDVALIDITY. A stale UID returns not_found.

• HTML-only messages use best-effort text extraction.

• The server has no conversation model, attachment download, BCC, HTML sending, or permanent-delete tool.

• Rate-limit state lives in memory and resets when the process restarts.

License

MIT