imap-mcp

A small MCP server that bridges one or more IMAP mailboxes over Streamable HTTP, so AI agents can read, search and triage mail, and optionally send it.

Enabled by default: reading, searching and read-status changes. No tool can move or delete mail; mark_read / mark_unread only touch the \Seen flag. Sending is off unless you set SMTP_ENABLED=true; when it is off, the send_message tool is not registered at all.

Tools

Message results include uidValidity as a decimal string. Pass it with the same account, folder and UID(s) to read_message, mark_read, and mark_unread. If the mailbox UIDVALIDITY changes, these operations reject the stale reference; list or search again before retrying.

If HTML-to-text conversion fails, read_message includes bodyUnavailable: "conversion_failed" while preserving available headers, attachment metadata, and any available text. The body may be incomplete even when truncated is false; truncated only indicates the character cap.

Related MCP server: Email MCP Server

Configuration (env vars only)

<NAME> is the account name upper-cased. See .env.example.

read_message rejects messages larger than 1 MiB of raw MIME data, including attachments, before parsing. It checks the reported size before downloading and enforces the byte cap during download, independently of MAX_BODY_CHARS.

Boolean settings accept true/false, 1/0, yes/no, and on/off (case-insensitive). Unset or empty values use the default; other values are rejected.

Numeric settings accept decimal digits only: ports must be 1–65535, and MAX_BODY_CHARS must be 1–1048576. Unset values use the defaults; empty or invalid values prevent startup.

Run

cp .env.example .env   # fill in real values; .env is git-ignored
docker run -d --name imap-mcp --restart unless-stopped \
  --env-file .env -p "$BIND_IP:8787:8787" \
  --read-only --cap-drop ALL --security-opt no-new-privileges \
  ghcr.io/edmundlimboen/imap-mcp:latest

Or docker compose up -d (binds to ${BIND_IP}:8787). Or locally: npm ci && npm run build && npm start.

Check: curl http://$BIND_IP:8787/health → {"ok":true}.

Add as an MCP connector

• URL: http://<BIND_IP>:8787/mcp

• Transport: Streamable HTTP

• Header: Authorization: Bearer <MCP_BEARER_TOKEN>

Example client config:

{
  "mcpServers": {
    "imap": {
      "url": "http://<BIND_IP>:8787/mcp",
      "headers": { "Authorization": "Bearer <MCP_BEARER_TOKEN>" }
    }
  }
}

Security

• Every request except GET /health needs the bearer token; compared in constant time (SHA-256 + timingSafeEqual).

• /health returns only {"ok":true}.

• The server is stateless: each POST to /mcp opens a fresh IMAP connection per tool call.

• Expose it only on a private network (e.g. Tailscale). It has no TLS of its own.

• Container runs as the non-root node user.

Development

The GreenMail smoke tests explicitly use new ImapBackend({ allowPlaintextForTests: true }) for their plaintext server. This option is rejected unless NODE_ENV=test; normal connections always require TLS.

npm ci
npm test                       # unit tests (mocked IMAP layer)
docker run -d -p 3025:3025 -p 3143:3143 \
  -e GREENMAIL_OPTS="-Dgreenmail.setup.test.all -Dgreenmail.hostname=0.0.0.0 -Dgreenmail.users=smoke:smoke@example.test -Dgreenmail.users.login=email" \
  greenmail/standalone:2.1.12
GREENMAIL_HOST=localhost npm test   # adds the end-to-end smoke test

CI runs both and publishes ghcr.io/edmundlimboen/imap-mcp:latest (and :<sha>) on pushes to main, and :X.Y.Z for vX.Y.Z tags.

SMTP results include status (submitted, partial_submission, or rejected), accepted, rejected, and rejectionDetails with recipient addresses and numeric SMTP rejection codes when available. sent is true only when all recipients were accepted for submission; this does not confirm delivery. A partial submission still saves a Sent copy. retryable lists only recipients with temporary (4xx) rejections; retry those later, never the accepted recipients. Permanent (5xx) or unknown rejections require review. Raw SMTP rejection text is omitted.

Request resource limits are shared by all stateless HTTP requests for the configured bearer token: 120 requests and 10 send attempts per rolling minute, at most 24 in-flight HTTP requests, 8 active tool operations globally, 2 per account, and 16 queued operations. HTTP admission failures return 429 with Retry-After; queue and send-quota failures return MCP tool errors. Requests and operations have a 30-second deadline (including queue time). Disconnects and MCP cancellation remove queued work and close active mail connections/downloads. A cancelled SMTP submission may already have been accepted by the mail server; verify delivery before retrying. Limits are process-local; replicas each have their own budget.