# IMAP mailbox [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/ni-c/imap-mcp  
**GitHub Stars:** 3  
**npm Downloads (last month):** 1276  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/imap-mailbox

## Description
Read, search and organise any IMAP mailbox, with writes off by default

## Tools
Capabilities this server exposes over MCP:

- **get_server_info** — Reports what this account and server can do: the configured mailbox, IMAP capabilities, which flags the mailbox stores permanently, whether the new-mail keyword can be used, and which tool groups are enabled. Start here when a call fails for reasons that sound like configuration.
- **list_mailboxes** — Lists every folder in the account with its message and unseen counts, its special-use role (drafts, sent, trash, junk) and whether it can hold messages. Use the returned "path" verbatim wherever a tool takes a mailbox.
- **list_messages** — Lists messages newest first, optionally narrowed by sender, recipient, subject, body text, date range or flags. With no criteria it simply pages through the mailbox. Every filter is applied by the mail server, so searching a large folder is cheap. Returns summaries only — use get_message for the body.
- **list_new_messages** — Returns messages this server has not handed over yet, newest first, and then marks them with the "AiSeen" keyword so the next call returns only what arrived since. This is separate from the human read/unread state, which is never touched. Use dry_run to preview without marking.
- **get_message** — Fetches one message by UID and returns its headers and text body, fenced as untrusted content, together with a server-side security assessment (SPF/DKIM/DMARC verdicts, prompt-injection and homoglyph signals) and the list of its attachments. Does not change the read state. Set include_thread to also list the surrounding conversation.
- **get_attachments** — Without part_id: lists the attachments of a message with their type, size, whether the policy allows fetching them and whether their text can be read. With part_id: returns that one attachment. Small text and images come back inline so you can read them; a PDF, Word, Excel, PowerPoint or OpenDocument file can be read as text with mode="text", which is the only way to read a document without access to this server's filesystem; anything else is written to the download directory, if one is configured, and you get the path. part_id must come from a listing call of this same tool. Executables are refused even when they claim to be something else — including when writing to disk.

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

```json
"mcpServers": {
  "imap-mailbox": {
    "command": "npx",
    "args": ["-y","@ni-c/imap-mcp"],
    "env": {
      "IMAP_HOST": "",
      "IMAP_USER": "",
      "IMAP_PASSWORD": ""
    }
  }
}
```

**Requires environment variables:** `IMAP_HOST`, `IMAP_USER`, `IMAP_PASSWORD` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What the IMAP mailbox MCP server does

The IMAP mailbox MCP server gives an MCP client access to an IMAP account without depending on a provider-specific API. It can inspect folders, search messages, read headers and bodies, retrieve attachments, update reversible flags, move or copy messages, manage folders, and save drafts. It cannot send mail; a saved draft remains in the mailbox for a person to review and send through a normal mail client.

Message content is handled as untrusted input. Bodies are fenced with per-call markers, and the server adds a security assessment covering authentication-result claims, possible prompt-injection patterns, and mixed-script text. It also removes some hidden or potentially tracking-oriented content before returning data. Folder names receive similar handling, with the original path retained for tool operations and a cleaned display form provided for reading.

## How it works

The server communicates with the mailbox using IMAP over a TLS-capable connection and exposes a compact set of grouped tools. `get_server_info` reports available capabilities and server flags. Listing tools cover folders, message searches, and messages not previously handed over. The new-message workflow uses an IMAP keyword, `AiSeen` by default, rather than changing the human-readable `\\Seen` state.

Write-related operations are disabled unless configuration enables them. The default configuration registers read tools only, so unavailable operations are not exposed to the client. Moving, deleting messages, and deleting folders use MCP elicitation where the client supports it. Otherwise, the server uses a two-call confirmation token; disabling elicitation does not remove that guard.

## Setup and configuration

The IMAP mailbox MCP server requires Node.js 22 or newer and an IMAP account. Set `IMAP_HOST`, `IMAP_USER`, and `IMAP_PASSWORD`; accounts protected by two-factor authentication may require an app-specific password. The default port is selected from the TLS mode, which defaults to implicit TLS. `IMAP_MAILBOX` sets the default folder for message tools.

Keep `IMAP_READ_ONLY` at its default value of `true` for read-only operation. Setting it exactly to `false` enables the mailbox write group. `IMAP_ALLOW_TOOLS` can restrict registration to named tools, `list_*` groups, or the `essential` set, while `IMAP_DENY_TOOLS` removes entries from the allowed set. `IMAP_SEEN_KEYWORD` controls new-message tracking, and `IMAP_TRUSTED_AUTHSERV_ID` identifies the provider-authenticated source for SPF, DKIM, and DMARC results.

## Tools and capabilities

The available tools cover:

- Server capability and flag inspection
- Folder listing with counts and special-use roles
- Message listing and filtering by participants, subject, body, dates, and flags
- One-time new-message retrieval with preview support
- Message reading with optional thread information
- Attachment listing, reading, extraction, and saving
- Reversible flag updates without allowing `\\Deleted`
- Message moving and copying
- Protected message and mailbox deletion
- Mailbox creation and protected renaming
- Draft creation without sending

## Limitations and notes

The IMAP mailbox MCP server does not send messages, and `save_draft` does not leave the mailbox. Provider behavior can affect supported flags, keyword storage, authentication headers, and folder operations. Authentication results are treated as forgeable unless a trusted authserv ID is configured. Client support for interactive elicitation also varies, so destructive operations may use token confirmation instead of a dialog.

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