@mindstone/mcp-server-email-imap

Email IMAP/SMTP MCP server for Model Context Protocol hosts. Read, search, send, and manage emails through IMAP and SMTP — supports iCloud Mail, Gmail, Yahoo Mail, Outlook / Microsoft 365, and custom IMAP providers.

Status

• Version: 0.3.2 · npm
• Auth: App password (EMAIL_IMAP_PASSWORD)
• Tools: 17 (mailbox, messages, drafts, send)
• Surface: local-protocol
• Machine-readable: STATUS.json

Requirements

• Node.js 20+
• npm

One-click install

After clicking the button, your host will prompt you to fill: EMAIL_IMAP_EMAIL, EMAIL_IMAP_PASSWORD, EMAIL_IMAP_IMAP_PORT, EMAIL_IMAP_SMTP_PORT, EMAIL_IMAP_MAX_RECIPIENTS, EMAIL_IMAP_RATE_LIMIT_PER_HOUR, EMAIL_IMAP_RATE_LIMIT_WINDOW_MS.

{
  "mcpServers": {
    "Email (IMAP/SMTP)": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-email-imap"
      ],
      "env": {
        "EMAIL_IMAP_EMAIL": "",
        "EMAIL_IMAP_PASSWORD": "",
        "EMAIL_IMAP_IMAP_PORT": "993",
        "EMAIL_IMAP_SMTP_PORT": "587",
        "EMAIL_IMAP_MAX_RECIPIENTS": "25",
        "EMAIL_IMAP_RATE_LIMIT_PER_HOUR": "50",
        "EMAIL_IMAP_RATE_LIMIT_WINDOW_MS": "3600000"
      }
    }
  }
}

Quick Start

Install & build

cd <path-to-repo>/connectors/email-imap
npm install
npm run build

npx (once published)

npx -y @mindstone/mcp-server-email-imap

Local

node dist/index.js

Configuration

Environment variables

• EMAIL_IMAP_EMAIL — email address
• EMAIL_IMAP_PASSWORD — app-specific password
• EMAIL_IMAP_PROVIDER — email provider (icloud, gmail, yahoo, outlook, or custom). When unset, the connector auto-detects the provider from the email's domain (e.g. @gmail.com → gmail, @icloud.com → icloud, @outlook.com → outlook, @yahoo.co.uk → yahoo). If the domain is not recognised, the connector refuses to start with a clear error — it will not silently fall back to a default provider.
• EMAIL_IMAP_IMAP_HOST — custom IMAP host (optional, for custom providers)
• EMAIL_IMAP_SMTP_HOST — custom SMTP host (optional, for custom providers)
• EMAIL_IMAP_IMAP_PORT — custom IMAP port (default: 993). Cleartext ports (imap_port=143, smtp_port=25) are allowed when configured — your host owns the plaintext decision.
• EMAIL_IMAP_SMTP_PORT — custom SMTP port (default: 587)
• MCP_WORKSPACE_PATH — workspace directory used for attachment file I/O. email_get_attachment downloads into a fresh, private email-imap-attachment-* staging directory created directly under this path (the returned path points there), and outbound attachments on email_send / email_save_draft / email_update_draft may only be read from inside it (paths outside — including via symlinks — are refused). Successful downloads keep their staging directory (it is the container of the returned file); accumulated email-imap-attachment-* directories are safe to delete once the files are no longer needed. Defaults to the system temp directory when unset.
• MCP_HOST_BRIDGE_STATE — optional path to a host bridge state file used for credential management
• MINDSTONE_REBEL_BRIDGE_STATE — backwards-compatible alias for MCP_HOST_BRIDGE_STATE

Send-side caps (email_send)

These caps act as blast-radius circuit breakers against prompt-injection-driven mass sends. Defaults are baked into the source so a host that sets none of these still gets safe behaviour. Hosts can tighten them per deployment.

• EMAIL_IMAP_MAX_RECIPIENTS — maximum combined To+CC+BCC recipients per email_send call (default: 25). Exceeding this returns a structured error with code: "RECIPIENT_LIMIT_EXCEEDED".
• EMAIL_IMAP_RATE_LIMIT_PER_HOUR — maximum number of email_send calls per rolling window (default: 50). Exceeding this returns a structured error with code: "RATE_LIMIT_EXCEEDED", plus resetAt (ISO-8601) and retryAfterMs so the host/LLM can back off.
• EMAIL_IMAP_RATE_LIMIT_WINDOW_MS — sliding-window length, in milliseconds, for the rate limit (default: 3600000 — one hour).

Host configuration examples

Claude Desktop / Cursor

{
  "mcpServers": {
    "Email": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-email-imap"],
      "env": {
        "EMAIL_IMAP_EMAIL": "you@icloud.com",
        "EMAIL_IMAP_PASSWORD": "your-app-specific-password",
        "EMAIL_IMAP_PROVIDER": "icloud"
      }
    }
  }
}

Local development (no npm publish needed)

{
  "mcpServers": {
    "Email": {
      "command": "node",
      "args": ["<path-to-repo>/connectors/email-imap/dist/index.js"],
      "env": {
        "EMAIL_IMAP_EMAIL": "you@icloud.com",
        "EMAIL_IMAP_PASSWORD": "your-app-specific-password",
        "EMAIL_IMAP_PROVIDER": "icloud"
      }
    }
  }
}

Security: host confirmation required for email_send

email_send is a destructive, open-world action: it dispatches mail to arbitrary external recipients on the user's behalf. The tool is annotated with destructiveHint: true and openWorldHint: true accordingly.

Hosts MUST require explicit user confirmation before each email_send invocation. A user-confirmation gate is the only reliable defence against prompt-injection content (e.g., text inside an email_get_message body) coercing the LLM into sending mail without the user's intent. Do not auto-approve email_send based on tool annotations alone — surface the full recipient list, subject, and body to the user and require an affirmative click/keystroke before forwarding the call to the connector.

The connector additionally enforces:

• A combined To+CC+BCC recipient cap (EMAIL_IMAP_MAX_RECIPIENTS, default 25).
• A per-process rolling rate limit (EMAIL_IMAP_RATE_LIMIT_PER_HOUR / EMAIL_IMAP_RATE_LIMIT_WINDOW_MS, defaults 50 / 3600000ms).

When either cap is exceeded the tool returns a structured error JSON ({ ok: false, code: "RECIPIENT_LIMIT_EXCEEDED" | "RATE_LIMIT_EXCEEDED", … }) without contacting the SMTP transport. Caps are env-tunable but defaults are baked into the source — hosts do not need to set any env var to get safe behaviour.

Security: untrusted-content envelopes and destructive tools

Every attacker-controlled text field the connector returns — message bodies, subjects, from/to display names, Message-IDs, attachment filenames, MIME content types and part identifiers, mailbox names and special-use values, message flag keywords (writable via email_set_flags, where keywords must match a conservative charset allowlist — letters, digits, _, $, ., - with an optional leading \ — so atom-specials like spaces, parens, quotes or CR/LF can never reach the IMAP command), draft summaries, and error text originating from the IMAP/SMTP server or vendor SDKs — is wrapped in an <untrusted-content …>…</untrusted-content> envelope (with close-tag breakout escaping) so the host LLM treats it as data, not instructions. Tools that consume a previously returned value (mailbox, part, mailbox names, flag keywords) accept the enveloped form as-is and strip one envelope layer on input.

Beyond email_send, the tools annotated destructiveHint: true are email_save_draft, email_update_draft (replaces and expunges the old draft), email_create_mailbox, email_rename_mailbox, email_delete (permanent when no Trash mailbox exists; aborts with a TRASH_MOVE_FAILED error — leaving the messages in place — when the move to Trash fails, rather than silently escalating to a permanent expunge), email_move_messages (its fallback permanently expunges the source messages, and only after the copy to the destination is verified complete for every UID — otherwise it aborts with a MOVE_COPY_UNVERIFIED error), email_set_flags (\Deleted marks messages for permanent expunge on mailbox close), email_delete_draft (always permanent), and email_delete_mailbox (removes the folder and all messages inside it). Hosts should gate these behind the same explicit user confirmation as email_send.

Tools (17)

Configuration

• configure_email_imap — Configure email account credentials and provider

Mailbox

• email_list_mailboxes — List all email folders/mailboxes with message counts
• email_get_mailbox_status — Get mailbox status with unread count and latest subjects
• email_create_mailbox — Create a new mailbox/folder (destructive)
• email_rename_mailbox — Rename a mailbox/folder (INBOX cannot be renamed; destructive)
• email_delete_mailbox — Permanently delete a mailbox/folder and its contents (destructive)

Messages

• email_search_messages — Search emails with sender/subject/unread filters, since/before date filters, and before_uid cursor pagination (returns at most 50 messages when limit is omitted; hasMore: true signals more results)
• email_get_message — Get full email content by UID (bodies, subjects, addresses, Message-ID, and attachment filenames/MIME metadata are returned inside <untrusted-content> envelopes)
• email_get_attachment — Download an attachment into the workspace sandbox (see MCP_WORKSPACE_PATH); writes are exclusive-create, so existing files are never overwritten
• email_move_messages — Move emails between folders (fallback expunge of the source is gated on a verified-complete copy; destructive)
• email_delete — Delete emails (moves to Trash when one exists, otherwise expunges permanently; aborts with an error if the Trash move fails; destructive)
• email_set_flags — Set or remove flags (read, starred) on messages (flag keywords are returned enveloped and must match a charset allowlist on input; destructive)

Drafts

• email_save_draft — Save a draft email (supports attachments; mutates the remote account — destructive)
• email_list_drafts — List drafts in the Drafts mailbox (at most 50 per call; hasMore: true signals more drafts)
• email_update_draft — Replace a draft's content (the new version is saved before the old one is removed; destructive)
• email_delete_draft — Permanently delete a draft (destructive)

Send

• email_send — Send an email or reply (supports attachments)

Licence

FSL-1.1-MIT — Functional Source License, Version 1.1, with MIT future licence. The software converts to MIT licence on 2030-04-08.