# io.github.nikolausm/imap-mcp-server (npm · imap-mcp-server)

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

- Trust score: 74/100 (medium)
- Change this week: +50
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `imap-mcp-server`: 74/100 (this document), [markdown](https://verifymcp.io/servers/nikolausm-imap-mcp-server/imap-mcp-server.md), [page](https://verifymcp.io/servers/nikolausm-imap-mcp-server/imap-mcp-server)

## Channel facts

- Registry: `npm`
- Package: `imap-mcp-server`
- Version: `1.5.2`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 87/100
  - No malware found by supply-chain analysis.
  - Only part of the dependency tree could be resolved (199 of 200), so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (199 of 200), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 97/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to nikolausm/imap-mcp-server).
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 17 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 65/100
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 7106 tokens (~177/item across 40 items; 40 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 0/100
  - Stability not yet verified: not enough scan history yet (needs a 30-day window).
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

**Unverified: 1 category.** A category scored 0 because we could not verify it: a data source with nothing on this package, evidence we could not reach, or a check we could not run. We only credit what we can confirm.

## Install

### Claude

```bash
claude mcp add nikolausm-imap-mcp-server -- npx -y imap-mcp-server
```

### Codex

```bash
codex mcp add nikolausm-imap-mcp-server -- npx -y imap-mcp-server
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "nikolausm-imap-mcp-server": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "imap-mcp-server"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add nikolausm-imap-mcp-server --command npx --arg -y --arg imap-mcp-server
```

### Hermes

```yaml
mcp_servers:
  nikolausm-imap-mcp-server:
    command: "npx"
    args: ["-y", "imap-mcp-server"]
```

### Other

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

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-02 (score 74, +69)

- [security improvement] Install scripts: unverified → pass
- [security improvement] Provenance: unverified → pass
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Malware scan: unverified → pass
- [security] Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window).
- [security] Stability: Stability not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.
- [security] The attested source repository moved: nikolausm/imap-mcp-server
- [functional regression] Security disclosure: fail → unverified
- [functional improvement] Tool coverage: unverified → 100
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] MCP protocol: unverified → pass
- [functional improvement] License: unverified → pass
- [functional] First check of Schema quality: fail
- [functional] First check of Schema quality: excellent
- [functional] First check of Schema quality: fail
- [functional] First check of Tool coverage: 100
- [functional] Capabilities: Protocol version not yet verified: we do not have a sandbox capture of the MCP handshake this version of the package performs yet.
- [functional] Tool coverage: Tool coverage not yet verified: we do not have a sandbox capture of the tool definitions this version of the package serves yet.
- [functional] Schema quality: Schema quality not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.
- [functional] Licence: MIT

### 2026-07-31 (score 5, −19)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-27 (score 24)

First indexed and scored.

## MCP tools (40)

### `imap_add_account` (~202 tokens)

Add a new IMAP account configuration

Input parameters:

- `email` (string): Email address (From: header). Defaults to user if omitted
- `host` (string, required): IMAP server hostname
- `name` (string, required): Friendly name for the account
- `password` (string, required): Password for authentication
- `port` (number): IMAP server port (default: 993)
- `smtpHost` (string): SMTP server hostname. Defaults to IMAP host with imap.→smtp. rewrite
- `smtpPort` (number): SMTP server port (465 for SMTPS, 587 for STARTTLS). Defaults to 587
- `smtpSecure` (boolean): Use implicit TLS (SMTPS). Ignored for port 587/25 which always use STARTTLS, and for port 465 which always uses implicit TLS
- `tls` (boolean): Use TLS/SSL (default: true)
- `user` (string, required): Username for authentication

### `imap_update_account` (~225 tokens)

Update an existing IMAP account. Useful for fixing SMTP settings without removing and re-adding the account.

Input parameters:

- `accountId` (string, required): ID of the account to update
- `email` (string): Email address (From: header)
- `host` (string): IMAP host
- `name` (string): New friendly name
- `password` (string): New password
- `port` (number): IMAP port
- `saveToSent` (boolean): Save sent emails to the Sent folder
- `smtpHost` (string): SMTP hostname
- `smtpPassword` (string): SMTP password (if different from IMAP password)
- `smtpPort` (number): SMTP port (465 for SMTPS, 587 for STARTTLS)
- `smtpSecure` (boolean): Use implicit TLS (SMTPS). Port 587/25 always use STARTTLS regardless
- `smtpUser` (string): SMTP username (if different from IMAP user)
- `tls` (boolean): Use TLS for IMAP
- `user` (string): IMAP username

### `imap_list_accounts` (~17 tokens)

List all configured IMAP accounts

### `imap_remove_account` (~31 tokens)

Remove an IMAP account configuration

Input parameters:

- `accountId` (string, required): ID of the account to remove

### `imap_connect` (~42 tokens)

Connect to an IMAP account

Input parameters:

- `accountId` (string): Account ID to connect to
- `accountName` (string): Account name to connect to

### `imap_disconnect` (~29 tokens)

Disconnect from an IMAP account

Input parameters:

- `accountId` (string, required): Account ID to disconnect from

### `imap_test_account` (~46 tokens)

Test an existing account connection without re-entering credentials. Validates IMAP connectivity and returns folder count and message count.

Input parameters:

- `accountId` (string, required): Account ID to test

### `imap_search_emails` (~893 tokens)

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.

Input parameters:

- `accountId` (string): Account ID (from imap_list_accounts). Optional if accountName is given or only one account is configured.
- `accountName` (string): Account name instead of accountId. Optional if accountId is given or only one account is configured.
- `before` (string): Search emails before date (YYYY-MM-DD)
- `body` (string): Search in body text
- `bodyFormat` (string): How to render the body when `includeBody` is true. Mirrors `imap_get_email` — "markdown" (default) returns clean Markdown and omits raw HTML so it never crosses the MCP boundary; "text" returns plain…
- `bodyMaxLength` (number): Per-message cap (in characters) for each rendered body field when `includeBody` is true. Defaults to 10000 to match `imap_get_email`.
- `flagged` (boolean): Filter by flagged status
- `folder` (string): Folder name to search (default: INBOX). Ignored when searchAllFolders is true.
- `from` (string): Search by sender
- `includeBody` (boolean): If true, also fetch the parsed message body in the same round-trip and return it alongside headers (avoids the N+1 cost of calling imap_get_email per match). Body is rendered per `bodyFormat` and cap…
- `includeDrafts` (boolean): When searchAllFolders is true, also search the Drafts folder (off by default).
- `includeSpam` (boolean): When searchAllFolders is true, also search Spam/Junk folders (off by default — noisy).
- `includeTrash` (boolean): When searchAllFolders is true, also search Trash/Bin/Deleted folders (off by default — noisy).
- `keywords` (array): Match messages that have ANY of these CUSTOM keywords (server-side OR; not system flags like \Seen/\Flagged). Read a mailbox's available custom keywords from imap_folder_status's customKeywords field…
- `limit` (number): Maximum number of results
- `messageId` (string): Search by RFC822 Message-ID header (substring match)
- `searchAllFolders` (boolean): Search across ALL folders instead of just `folder`. Skips Trash/Spam/Drafts and non-selectable folders by default. Use when a message might have been filed/archived/moved and you do not know which fo…
- `seen` (boolean): Filter by read/unread status
- `since` (string): Search emails since date (YYYY-MM-DD)
- `subject` (string): Search by subject
- `to` (string): Search by recipient
- `unKeywords` (array): Exclude messages that have ANY of these CUSTOM keywords (server-side; result has NONE of them). Same keyword source as `keywords` — check imap_folder_status first.

### `imap_get_email` (~363 tokens)

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.

Input parameters:

- `accountId` (string): Account ID (from imap_list_accounts). Optional if accountName is given or only one account is configured.
- `accountName` (string): Account name instead of accountId. Optional if accountId is given or only one account is configured.
- `bodyFormat` (string): How to return the body. "markdown" (default): clean Markdown via Turndown in markdownContent, raw htmlContent omitted so HTML never crosses the boundary. "text": plain text only in textContent. "html…
- `folder` (string): Folder name
- `includeAttachmentText` (boolean): Include text attachment previews when available
- `includeHeaders` (boolean): Include raw email headers (e.g. List-Unsubscribe, List-Unsubscribe-Post)
- `maxAttachmentTextChars` (number): Maximum characters to return per text attachment
- `maxContentLength` (number): Maximum characters to return for each body field (text/markdown/html)
- `uid` (number, required): Email UID

### `imap_upload_file` (~129 tokens)

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).

Input parameters:

- `content` (string, required): Base64 encoded file content
- `contentType` (string): MIME type (optional, used for metadata only)
- `filename` (string, required): Filename to save as

### `imap_download_attachment` (~217 tokens)

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.

Input parameters:

- `accountId` (string): Account ID (from imap_list_accounts). Optional if accountName is given or only one account is configured.
- `accountName` (string): Account name instead of accountId. Optional if accountId is given or only one account is configured.
- `extractText` (boolean): For PDFs, extract and return text content inline
- `filename` (string, required): Attachment filename or contentId
- `folder` (string): Folder name
- `savePath` (string): Optional file path to save the attachment to. If not provided, files are saved to the shared downloads directory.
- `uid` (number, required): Email UID

### `imap_mark_as_read` (~166 tokens)

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).

Input parameters:

- `accountId` (string): Account ID (from imap_list_accounts). Optional if accountName is given or only one account is configured.
- `accountName` (string): Account name instead of accountId. Optional if accountId is given or only one account is configured.
- `folder` (string): Folder name
- `uid` (required): Email UID, or array of UIDs to mark as read in one call (avoids N round-trips when triaging). All listed UIDs share the same IMAP STORE command, so the operation is atomic at the server level.

### `imap_mark_as_unread` (~161 tokens)

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.

Input parameters:

- `accountId` (string): Account ID (from imap_list_accounts). Optional if accountName is given or only one account is configured.
- `accountName` (string): Account name instead of accountId. Optional if accountId is given or only one account is configured.
- `folder` (string): Folder name
- `uid` (required): Email UID, or array of UIDs to mark as unread in one call (avoids N round-trips when triaging). All listed UIDs share the same IMAP STORE command, so the operation is atomic at the server level.

### `imap_flag_email` (~130 tokens)

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.

Input parameters:

- `accountId` (string): Account ID (from imap_list_accounts). Optional if accountName is given or only one account is configured.
- `accountName` (string): Account name instead of accountId. Optional if accountId is given or only one account is configured.
- `folder` (string): Folder name
- `uid` (number, required): Email UID

### `imap_unflag_email` (~201 tokens)

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.

Input parameters:

- `accountId` (string): Account ID (from imap_list_accounts). Optional if accountName is given or only one account is configured.
- `accountName` (string): Account name instead of accountId. Optional if accountId is given or only one account is configured.
- `folder` (string): Folder name
- `uid` (number, required): Email UID

### `imap_add_keyword` (~276 tokens)

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.

Input parameters:

- `accountId` (string): Account ID (from imap_list_accounts). Optional if accountName is given or only one account is configured.
- `accountName` (string): Account name instead of accountId. Optional if accountId is given or only one account is configured.
- `folder` (string): Folder name
- `keyword` (string, required): IMAP keyword to set, passed through verbatim (e.g. "$cl_3", "$MailFlagBit0", "$Junk")
- `uid` (number, required): Email UID

### `imap_remove_keyword` (~277 tokens)

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.

Input parameters:

- `accountId` (string): Account ID (from imap_list_accounts). Optional if accountName is given or only one account is configured.
- `accountName` (string): Account name instead of accountId. Optional if accountId is given or only one account is configured.
- `folder` (string): Folder name
- `keyword` (string, required): IMAP keyword to remove, passed through verbatim (e.g. "$cl_3", "$MailFlagBit0", "$Junk")
- `uid` (number, required): Email UID

### `imap_delete_email` (~163 tokens)

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.

Input parameters:

- `accountId` (string): Account ID (from imap_list_accounts). Optional if accountName is given or only one account is configured.
- `accountName` (string): Account name instead of accountId. Optional if accountId is given or only one account is configured.
- `folder` (string): Folder name
- `uid` (number, required): Email UID

### `imap_move_email` (~201 tokens)

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.

Input parameters:

- `accountId` (string): Account ID (from imap_list_accounts). Optional if accountName is given or only one account is configured.
- `accountName` (string): Account name instead of accountId. Optional if accountId is given or only one account is configured.
- `createDestinationIfMissing` (boolean): If true, create the destination folder before moving when it does not exist (default: false)
- `folder` (string): Source folder name
- `targetFolder` (string, required): Destination folder name
- `uid` (required): Single email UID or array of UIDs to move in one call. Pass an array when triaging many messages at once (e.g. "move the 10 invoices I just classified to Archive") to avoid N round-trips.

### `imap_bulk_delete` (~134 tokens)

Delete multiple emails at once with chunking and auto-reconnection. Processes deletions in batches to prevent connection timeouts.

Input parameters:

- `accountId` (string): Account ID (from imap_list_accounts). Optional if accountName is given or only one account is configured.
- `accountName` (string): Account name instead of accountId. Optional if accountId is given or only one account is configured.
- `chunkSize` (number): Number of emails to delete per batch (default: 50)
- `folder` (string): Folder name
- `uids` (array, required): Array of email UIDs to delete

### `imap_bulk_delete_by_search` (~243 tokens)

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.

Input parameters:

- `accountId` (string): Account ID (from imap_list_accounts). Optional if accountName is given or only one account is configured.
- `accountName` (string): Account name instead of accountId. Optional if accountId is given or only one account is configured.
- `before` (string): Delete emails before this date (YYYY-MM-DD)
- `chunkSize` (number): Number of emails to delete per batch
- `dryRun` (boolean): If true, only return what would be deleted without actually deleting
- `folder` (string): Folder name
- `from` (string): Delete emails from this sender
- `since` (string): Delete emails since this date (YYYY-MM-DD)
- `subject` (string): Delete emails with this subject
- `to` (string): Delete emails to this recipient

### `imap_get_latest_emails` (~361 tokens)

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.

Input parameters:

- `accountId` (string): Account ID (from imap_list_accounts). Optional if accountName is given or only one account is configured.
- `accountName` (string): Account name instead of accountId. Optional if accountId is given or only one account is configured.
- `bodyFormat` (string): How to render the body when `includeBody` is true. Mirrors `imap_get_email` — "markdown" (default) returns clean Markdown; "text" returns plain text; "html" returns raw HTML; "auto" prefers substanti…
- `bodyMaxLength` (number): Per-message cap (in characters) for each rendered body field when `includeBody` is true. Defaults to 10000 to match `imap_get_email`.
- `count` (number): Number of emails to retrieve
- `folder` (string): Folder name
- `includeBody` (boolean): If true, also fetch the parsed message body in the same round-trip and return it alongside headers (avoids the N+1 cost of calling imap_get_email per message). Body is rendered per `bodyFormat` and c…

### `imap_send_email` (~261 tokens)

Compose and send a NEW email via the account's SMTP server (a copy is saved to Sent unless disabled). 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).

Input parameters:

- `accountId` (string): Account ID (from imap_list_accounts). Optional if accountName is given or only one account is configured.
- `accountName` (string): Account name instead of accountId. Optional if accountId is given or only one account is configured.
- `attachments` (array): Email attachments
- `bcc`: BCC recipients
- `body` (string): Alias for 'text' (backward-compat with clients that pass 'body')
- `cc`: CC recipients
- `html` (string): HTML content
- `replyTo` (string): Reply-to address
- `subject` (string, required): Email subject
- `text` (string): Plain text content
- `to` (required): Recipient email address(es)

### `imap_save_draft` (~228 tokens)

Save an email as a draft in the Drafts folder (no send). Takes the same fields as imap_send_email.

Input parameters:

- `accountId` (string): Account ID (from imap_list_accounts). Optional if accountName is given or only one account is configured.
- `accountName` (string): Account name instead of accountId. Optional if accountId is given or only one account is configured.
- `attachments` (array): Email attachments
- `bcc`: BCC recipients
- `body` (string): Alias for 'text' (backward-compat)
- `cc`: CC recipients
- `folder` (string): Override the Drafts folder name (defaults to auto-detected Drafts folder)
- `html` (string): HTML content
- `inReplyTo` (string): Message-Id being replied to
- `references`: References header value(s)
- `replyTo` (string): Reply-to address
- `subject` (string): Email subject
- `text` (string): Plain text content
- `to`: Recipient email address(es)

### `imap_reply_to_email` (~221 tokens)

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 recipients. Use this instead of imap_send_email whenever the user is responding to a message already in a mailbox.

Input parameters:

- `accountId` (string): Account ID (from imap_list_accounts). Optional if accountName is given or only one account is configured.
- `accountName` (string): Account name instead of accountId. Optional if accountId is given or only one account is configured.
- `attachments` (array): Email attachments
- `body` (string): Alias for 'text' (backward-compat)
- `folder` (string): Folder containing the original email
- `html` (string): HTML reply content
- `replyAll` (boolean): Reply to all recipients
- `text` (string): Plain text reply content
- `uid` (number, required): UID of the email to reply to

### `imap_forward_email` (~195 tokens)

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.

Input parameters:

- `accountId` (string): Account ID (from imap_list_accounts). Optional if accountName is given or only one account is configured.
- `accountName` (string): Account name instead of accountId. Optional if accountId is given or only one account is configured.
- `body` (string): Alias for 'text' (backward-compat)
- `folder` (string): Folder containing the original email
- `includeAttachments` (boolean): Include original attachments
- `text` (string): Additional text to include
- `to` (required): Forward to email address(es)
- `uid` (number, required): UID of the email to forward

### `imap_find_thread_messages` (~397 tokens)

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.

Input parameters:

- `accountId` (string): Account ID (from imap_list_accounts). Optional if accountName is given or only one account is configured.
- `accountName` (string): Account name instead of accountId. Optional if accountId is given or only one account is configured.
- `bodyFormat` (string): How to render the body when `includeBody` is true. Mirrors `imap_get_email` — "markdown" (default) returns clean Markdown; "text" returns plain text; "html" returns raw HTML; "auto" prefers substanti…
- `bodyMaxLength` (number): Per-message cap (in characters) for each rendered body field when `includeBody` is true. Defaults to 10000 to match `imap_get_email`.
- `includeBody` (boolean): If true, also fetch the parsed message body for each found thread message in the same round-trip and return it alongside headers (avoids the N+1 cost of calling imap_get_email per thread member). Bod…
- `searchFolder` (string): Folder to search for related thread messages (default: INBOX)
- `searchReferences` (boolean): Also search the References header for multi-level threads (default: true)
- `sourceFolder` (string, required): Folder containing the already-sorted thread messages (e.g. "Review.Articles")

### `imap_find_email_by_message_id` (~144 tokens)

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.

Input parameters:

- `accountId` (string, required): Account ID
- `folders` (array): Explicit folders to search, in order (overrides the default order)
- `messageId` (string, required): RFC822 Message-ID, with or without angle brackets

### `imap_list_folders` (~129 tokens)

List all folders/mailboxes for an account (names, hierarchy delimiter, attributes). 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").

Input parameters:

- `accountId` (string): Account ID (from imap_list_accounts). Optional if accountName is given or only one account is configured.
- `accountName` (string): Account name instead of accountId. Optional if accountId is given or only one account is configured.

### `imap_folder_status` (~82 tokens)

Get status information about a folder

Input parameters:

- `accountId` (string): Account ID (from imap_list_accounts). Optional if accountName is given or only one account is configured.
- `accountName` (string): Account name instead of accountId. Optional if accountId is given or only one account is configured.
- `folder` (string, required): Folder name

### `imap_create_folder` (~155 tokens)

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.

Input parameters:

- `accountId` (string): Account ID (from imap_list_accounts). Optional if accountName is given or only one account is configured.
- `accountName` (string): Account name instead of accountId. Optional if accountId is given or only one account is configured.
- `folder` (string, required): Full folder path to create (e.g. "Archives/2026/2026-05" or "INBOX.Archive")

### `imap_get_unread_count` (~128 tokens)

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.

Input parameters:

- `accountId` (string): Account ID (from imap_list_accounts). Optional if accountName is given or only one account is configured.
- `accountName` (string): Account name instead of accountId. Optional if accountId is given or only one account is configured.
- `folders` (array): List of folders to check (default: all)

### `imap_check_spam` (~254 tokens)

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.

Input parameters:

- `accountId` (string, required): Account ID
- `folder` (string): Folder name
- `from` (string): Filter by sender (optional)
- `includeHeaderChecks` (boolean): Also run deterministic raw-header checks (X-Mailer bulk tools, Precedence: bulk, DMARC/SPF/DKIM failures, List-Unsubscribe/Reply-To domain mismatches) on top of the sender-domain check. Fetches messa…
- `limit` (number): Maximum number of emails to check
- `since` (string): Check emails since date (YYYY-MM-DD)

### `imap_delete_spam` (~88 tokens)

Find and delete emails from known spam/disposable email domains.

Input parameters:

- `accountId` (string, required): Account ID
- `dryRun` (boolean): If true, only report what would be deleted without deleting
- `folder` (string): Folder name
- `limit` (number): Maximum number of emails to check
- `minConfidence` (string): Minimum confidence level for spam detection

### `imap_domain_stats` (~76 tokens)

Get statistics about sender domains in a folder. Useful for identifying bulk senders or spam patterns.

Input parameters:

- `accountId` (string, required): Account ID
- `folder` (string): Folder name
- `limit` (number): Maximum number of emails to analyze
- `minCount` (number): Minimum email count per domain to include

### `imap_add_spam_domain` (~52 tokens)

Add a domain to the custom spam list. Emails from this domain will be flagged as spam.

Input parameters:

- `domain` (string, required): Domain to add to spam list (e.g., "spammer.com")

### `imap_remove_spam_domain` (~34 tokens)

Remove a domain from the custom spam list.

Input parameters:

- `domain` (string, required): Domain to remove from spam list

### `imap_add_whitelist_domain` (~48 tokens)

Add a domain to the whitelist. Emails from whitelisted domains will never be flagged as spam.

Input parameters:

- `domain` (string, required): Domain to whitelist (e.g., "trusted.com")

### `imap_list_spam_domains` (~23 tokens)

List all known spam domains (built-in and custom).

### `imap_delete_by_domain` (~84 tokens)

Delete all emails from a specific domain. Useful for cleaning up unwanted newsletters or spam.

Input parameters:

- `accountId` (string, required): Account ID
- `domain` (string, required): Domain to delete emails from (e.g., "spammer.com")
- `dryRun` (boolean): If true, only report what would be deleted
- `folder` (string): Folder name

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/nikolausm-imap-mcp-server/imap-mcp-server#diagnostics

## Score history

- 2026-08-03: 74
- 2026-08-02: 74
- 2026-08-01: 5
- 2026-07-31: 5
- 2026-07-30: 24
- 2026-07-28: 24
- 2026-07-27: 24

## Links

- npm package: https://www.npmjs.com/package/imap-mcp-server
- Socket report: https://socket.dev/npm/package/imap-mcp-server
- Repository: https://github.com/nikolausm/imap-mcp-server
- Changelog RSS feed: https://verifymcp.io/servers/nikolausm-imap-mcp-server/imap-mcp-server/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/nikolausm-imap-mcp-server/imap-mcp-server/changelog.json
- HTML version of this page: https://verifymcp.io/servers/nikolausm-imap-mcp-server/imap-mcp-server