# imap-mcp-server [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/nikolausm/imap-mcp-server  
**GitHub Stars:** 111  
**npm Downloads (last month):** 6300  
**Views:** 7  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/imap-mcp-server

## Description
IMAP/SMTP MCP server to search, read, organize, send, reply & forward email for AI assistants

## Tools
Capabilities this server exposes over MCP:

- **imap_add_account** — Add a new IMAP account configuration
- **imap_update_account** — Update an existing IMAP account. Useful for fixing SMTP settings without removing and re-adding the account.
- **imap_list_accounts** — List all configured IMAP accounts
- **imap_remove_account** — Remove an IMAP account configuration
- **imap_connect** — Connect to an IMAP account
- **imap_disconnect** — Disconnect from an IMAP account
- **imap_test_account** — Test an existing account connection without re-entering credentials. Validates IMAP connectivity and returns folder count and message count.
- **imap_search_emails** — Note: on some servers a 'flagged' or starred message carries a custom keyword (e.g. an Open-Xchange color label or Apple's $MailFlagBit*) instead of, or in addition to, the \Flagged system flag. After any flagged search, inspect each result's customKeywords field before concluding a message is or isn't flagged — do not rely on the flagged filter alone. Search for emails matching criteria (sender, recipient, subject, body text, date range, read/flagged status). Use this to FIND messages when you know something about them but not their UID — e.g. "emails from amazon last week", "unread invoices". By default searches a single folder (INBOX). Set searchAllFolders=true to scan every mailbox at once — this catches messages filed away by rules (e.g. a receipt routed to a custom folder); Trash/Spam/Drafts are skipped unless you opt in. By default returns lightweight headers (uid, from, subject, date, and folder when searching across folders); set `includeBody=true` to also return the parsed body in one round-trip instead of paying the N+1 cost of calling imap_get_email per match. For the newest messages without criteria, prefer imap_get_latest_emails.
- **imap_get_email** — Read the FULL content of a single email by its UID (body, sender/recipients, date, attachment list, optional raw headers and text-attachment previews). By default the body is returned as clean Markdown in markdownContent and raw HTML is omitted so it never crosses the boundary; set bodyFormat to "html" for the legacy raw htmlContent, or "text" for plain text only. Use after imap_search_emails or imap_get_latest_emails gives you a uid. Body text is truncated to maxContentLength to protect the context window — raise it for long messages. To fetch attachment bytes, use imap_download_attachment.
- **imap_upload_file** — Upload a file to the server for use as an email attachment. Returns a path that can be used with imap_send_email attachments. This allows sending large attachments without hitting context window limits. Max size: 26214400 bytes (configurable via IMAP_MAX_UPLOAD_SIZE). Uploads are auto-deleted after 86400000 ms (configurable via IMAP_UPLOAD_TTL_MS).
- **imap_download_attachment** — Download a single attachment from an email (folder + uid + attachment filename/contentId, as listed by imap_get_email). Images are returned inline for viewing; PDFs are saved and their text is extracted inline (extractText); other files are saved to the shared downloads directory (or savePath). Use when the user wants the actual file contents, not just the message body.
- **imap_mark_as_read** — Mark one or many emails as read. Accepts a single UID or an array — pass an array to flag N messages in one IMAP STORE round-trip (useful when triaging).
- **imap_mark_as_unread** — Mark one or many emails as unread. Accepts a single UID or an array — pass an array to flag N messages in one IMAP STORE round-trip.
- **imap_flag_email** — Flag an email — sets the IMAP \Flagged system flag (shows as a star in Gmail / a flag in Apple Mail). Use this tool when a user asks to star, flag, or mark a message as important.
- **imap_unflag_email** — Unflag an email — removes the IMAP \Flagged system flag (the star in Gmail, the flag in Apple Mail). Note: some servers (e.g. Open-Xchange / Network Solutions) and Apple Mail also write a separate custom keyword such as $cl_N or $MailFlagBit* when a message is flagged in their client. Removing \Flagged alone does not clear that keyword, so the message may still display as flagged. If it does, check the message's customKeywords via imap_get_email and remove the lingering label with imap_remove_keyword.
- **imap_add_keyword** — Set an arbitrary custom (non-system) IMAP keyword/label on an email — e.g. a provider color label like Open-Xchange's $cl_1..$cl_10, Apple Mail's $MailFlagBit0..$MailFlagBit2, or an app tag such as $promotion. Unlike imap_flag_email (which only ever sets the system \Flagged flag), this passes the keyword through verbatim, but rejects backslash-prefixed system flags (e.g. \Flagged, \Seen, \Deleted) — use the dedicated flag/read tools for those. Not every IMAP server permits custom keywords (see the mailbox's PERMANENTFLAGS) — if the server rejects or silently ignores the change, this call fails rather than reporting success.
- **imap_remove_keyword** — Remove an arbitrary custom (non-system) IMAP keyword/label from an email — e.g. a provider color label like Open-Xchange's $cl_1..$cl_10, Apple Mail's $MailFlagBit0..$MailFlagBit2, or an app tag such as $promotion. Unlike imap_unflag_email (which only ever clears the system \Flagged flag), this passes the keyword through verbatim, but rejects backslash-prefixed system flags (e.g. \Flagged, \Seen, \Deleted) — use the dedicated flag/read tools for those. Not every IMAP server permits custom keywords (see the mailbox's PERMANENTFLAGS) — if the server rejects or silently ignores the change, this call fails rather than reporting success.
- **imap_delete_email** — Delete ONE email by folder + uid (moves to Trash or expunges, server-dependent). Destructive and not easily undone — confirm the user means this specific message. To remove many at once use imap_bulk_delete (known uids) or imap_bulk_delete_by_search (by criteria, supports dryRun). To file an email away instead of deleting, use imap_move_email.
- **imap_move_email** — Move an email from one folder to another (e.g., INBOX to Taxes, or INBOX to Archive). Optionally creates the destination folder if it does not exist.
- **imap_bulk_delete** — Delete multiple emails at once with chunking and auto-reconnection. Processes deletions in batches to prevent connection timeouts.
- **imap_bulk_delete_by_search** — Search for emails matching criteria and delete them all. Useful for cleaning up spam or unwanted emails. At least one concrete criterion (from, to, subject, before, or since) is REQUIRED — a call with no criteria is refused so it can never wipe an entire folder. Supports dryRun to preview matches first.
- **imap_get_latest_emails** — Get the most recent emails from a folder, newest first. Use this for "what just came in?" / "show my latest inbox messages" when no search filter is needed. By default returns lightweight headers (uid, from, subject, date); set `includeBody=true` to also return the parsed body in one round-trip instead of paying the N+1 cost of calling imap_get_email per message. To filter by sender/subject/date instead, use imap_search_emails.
- **imap_send_email** — Compose and send a NEW email via the account's SMTP server (a copy is saved to Sent unless disabled; account defaultBcc addresses are always BCC'd when configured). Use for fresh outbound messages. To respond to an existing message use imap_reply_to_email (keeps threading); to pass a message on use imap_forward_email; to store without sending use imap_save_draft. Supports to/cc/bcc, text and/or HTML, and attachments by base64 content or by file path (see imap_upload_file for large files).
- **imap_save_draft** — Save an email as a draft in the Drafts folder (no send). Takes the same fields as imap_send_email (including account defaultBcc when configured).
- **imap_reply_to_email** — Reply to an existing email identified by folder + uid. Automatically sets the recipient to the original sender, prefixes the subject with "Re:", and preserves threading (In-Reply-To/References). Set replyAll to also include the original To (and Cc as Cc), excluding the account's own address; a Reply-To header on the original is honoured. Use this instead of imap_send_email whenever the user is responding to a message already in a mailbox. Account defaultBcc addresses are always BCC'd when configured.
- **imap_forward_email** — Forward an existing email (folder + uid) to new recipients, quoting the original message and headers. Optionally include the original attachments. Use when the user wants to pass an existing message on to someone else; use imap_reply_to_email instead to respond to the sender. Account defaultBcc addresses are always BCC'd when configured.
- **imap_find_thread_messages** — Find messages in `searchFolder` that belong to the same conversation threads as messages already in `sourceFolder`. Useful for catching replies that arrived after a thread was sorted. Works on any IMAP server (uses RFC 3501 HEADER search on In-Reply-To and References). Set `includeBody=true` to also return the parsed body for each found thread message in one round-trip — avoids the N+1 cost of calling imap_get_email per thread member.
- **imap_find_email_by_message_id** — Locate an email by its RFC822 Message-ID across folders and return its current { folder, uid } plus basic envelope. Robust to the message having been moved or archived (IMAP UIDs are folder-relative). Pass the returned folder + uid to imap_reply_to_email or imap_get_email. Without `folders`, searches Gmail \All Mail when present, else INBOX → Archive → Sent → remaining folders.
- **imap_list_folders** — List all folders/mailboxes for an account (names, hierarchy delimiter, attributes, RFC 6154 special-use role). Use this first to discover exact folder names before searching, moving, or creating subfolders — folder naming varies by provider (e.g. "Archive" vs "[Gmail]/All Mail" vs "INBOX.Archive"). The specialUse field ("\\Sent", "\\Drafts", "\\Trash", "\\Junk", "\\Archive") identifies a folder's role independent of its localized name (e.g. "Gesendet" is the Sent folder when specialUse is "\\Sent").
- **imap_folder_status** — Get status information about a folder
- **imap_create_folder** — Create a new IMAP folder/mailbox. Most servers also create any missing parent folders (e.g. creating "Archives/2026/2026-05" auto-creates "Archives" and "Archives/2026"). Returns success even if the folder already exists.
- **imap_get_unread_count** — Count unread (unseen) emails per folder, plus a total. Use for "how many unread do I have?" overviews. Defaults to all folders; pass a folders list to limit scope and speed it up.
- **imap_check_spam** — Check emails in a folder for spam. Combines sender-domain checks (known spam/disposable domains, suspicious patterns) with deterministic raw-header analysis: bulk-mailer X-Mailer/User-Agent signatures, Precedence: bulk, DMARC/SPF/DKIM failures in Authentication-Results, and List-Unsubscribe / Reply-To domains that do not match the sender. Header checks catch scam mail from fresh, unlisted domains that pass the domain check. Returns domain-based spam, a separate list of header-flagged mails, and domain statistics.
- **imap_delete_spam** — Find and delete emails from known spam/disposable email domains.
- **imap_domain_stats** — Get statistics about sender domains in a folder. Useful for identifying bulk senders or spam patterns.
- **imap_add_spam_domain** — Add a domain to the custom spam list. Emails from this domain will be flagged as spam.
- **imap_remove_spam_domain** — Remove a domain from the custom spam list.
- **imap_add_whitelist_domain** — Add a domain to the whitelist. Emails from whitelisted domains will never be flagged as spam.
- **imap_list_spam_domains** — List all known spam domains (built-in and custom).
- **imap_delete_by_domain** — Delete all emails from a specific domain. Useful for cleaning up unwanted newsletters or spam.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "imap-mcp-server": {
    "command": "npx",
    "args": ["-y","imap-mcp-server"]
  }
}
```

## Documentation

## What imap-mcp-server MCP server does

The imap-mcp-server MCP server gives an MCP-compatible assistant access to mailbox and email actions through IMAP and SMTP. It supports searching and reading messages, moving or deleting them, marking messages, and performing bulk deletion. Mailbox functions also include listing folders, checking folder status, and retrieving unread counts.

SMTP capabilities cover sending new messages, replying, and forwarding. Multiple accounts can be configured and managed at the same time, which makes the server suitable for assistants that work with separate personal, work, or service mailboxes.

## How it works

The server runs as a Node.js process and communicates with the MCP client over its configured local process connection. It can be started with `npx` or from a locally cloned and built project. Node.js 22.12 or newer is required.

Account data is stored in `~/.imap-mcp/accounts.json`. Credentials in that file are protected with AES-256 encryption. IMAP connections are managed through a connection pool rather than opening an unrelated connection for every operation.

The setup wizard provides presets for Gmail and Google Workspace, Microsoft Outlook, Yahoo Mail, Apple iCloud Mail, GMX, WEB.DE, IONOS, ProtonMail with Bridge, Fastmail, Zoho Mail, AOL Mail, mailbox.org, Posteo, and custom IMAP servers. SMTP settings can be filled automatically from the selected IMAP provider.

## Setup and configuration

Install by running the published package with `npx`, using the provided macOS/Linux or Windows installer, or cloning the repository and running `npm install` followed by `npm run build`. The web setup wizard can be launched with `npm run setup`, the global `imap-setup` command, or `npx -p imap-mcp-server imap-setup`. It starts a local web server and opens the configuration interface in a browser.

The imap-mcp-server MCP server can also add an account through the `imap_add_account` tool after it has been connected to an assistant. Account records are shared across npx, global, and local run modes, so an account normally needs to be configured only once.

Credential values may be supplied at runtime instead of being saved in the account file. For an account named `Work Gmail`, the supported variables use its normalized name: `IMAP_MCP_ACCOUNT_WORK_GMAIL_IMAP_USERNAME`, `IMAP_MCP_ACCOUNT_WORK_GMAIL_IMAP_PASSWORD`, `IMAP_MCP_ACCOUNT_WORK_GMAIL_SMTP_USERNAME`, and `IMAP_MCP_ACCOUNT_WORK_GMAIL_SMTP_PASSWORD`. These overrides apply only to existing accounts, are read at startup, and require a restart after changes.

## Tools and capabilities

The available operations cover:

- Searching and reading email
- Moving, marking, deleting, and bulk-deleting messages
- Sending, replying to, and forwarding messages through SMTP
- Listing folders and checking folder status
- Checking unread counts
- Managing multiple mail accounts
- Adding or updating account configuration
- Restricting exposure to read-only tools with `IMAP_MCP_READ_ONLY`

When read-only mode is enabled with a truthy value such as `1`, `true`, `yes`, or `on`, the server registers safe read operations, including search, message reading, folder listing, unread counts, and spam analysis. Sending mail and message-changing operations are excluded in that mode.

## Limitations and notes

The server requires Node.js 22.12 or newer. SMTP credential overrides work only when the account already has SMTP configuration. Environment-managed credentials are captured when the process starts; setting a variable after launch has no effect until restart.

If an account expects an environment-managed credential and the corresponding variable is absent, the server refuses the connection rather than attempting authentication with a blank value. The setup wizard can test credentials without saving them and displays the variable name needed for later runtime injection.

Provider presets cover the listed services, but custom IMAP servers can also be configured. ProtonMail support depends on ProtonMail Bridge. The supplied configuration examples document Claude Desktop and Claude Code; other clients need a compatible MCP stdio configuration.

_Full upstream README: https://allmcps.com/mcp/imap-mcp-server/readme_