@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
Requirements
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.
Manual config for Claude Desktop / Claude Code / Goose / Continue.dev (Email (IMAP/SMTP))
{
"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
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.
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.