Imap

IMAP MCP Server

A powerful Model Context Protocol (MCP) server that provides seamless IMAP email integration with secure account management and connection pooling.

Features

• 🔐 Secure Account Management: Encrypted credential storage with AES-256 encryption
• 🚀 Connection Pooling: Efficient IMAP connection management
• 📧 Comprehensive Email Operations: Search, read, move, mark, delete, and bulk delete emails
• ✉️ Email Sending: Send, reply, and forward emails via SMTP
• 📁 Folder Management: List folders, check status, get unread counts
• 🔄 Multiple Account Support: Manage multiple IMAP accounts simultaneously
• 🛡️ Type-Safe: Built with TypeScript for reliability
• 🌐 Web-Based Setup Wizard: Easy account configuration with provider presets
• 📱 15+ Email Providers: Pre-configured settings for Gmail, Outlook, Yahoo, and more
• 🔗 Auto SMTP Configuration: Automatic SMTP settings based on IMAP provider

Installation

Requires Node.js 22.12 or newer. Node 18 and 20 have both reached end-of-life, and several of this package's dependencies no longer support them. Check yours with node --version.

Run via npx (No Installation Required)

Once published to npm, you can run the server directly without cloning or building anything — npx downloads the prebuilt package and runs it:

npx -y imap-mcp-server

This is the easiest way to use the server in an MCP client (see Configuration for ready-to-paste npx configs).

Quick Install (Recommended)

macOS/Linux:

curl -fsSL https://raw.githubusercontent.com/nikolausm/imap-mcp-server/main/install.sh | bash

Windows (PowerShell as Administrator):

iwr -useb https://raw.githubusercontent.com/nikolausm/imap-mcp-server/main/install.ps1 | iex

Manual Installation

1. Clone the repository:

git clone https://github.com/nikolausm/imap-mcp-server.git
cd imap-mcp-server

2. Install dependencies:

npm install

3. Build the project:

npm run build

Account Setup

Accounts are stored encrypted in ~/.imap-mcp/accounts.json. This file is shared by all run modes — whether you start the server via npx, a global install, or a local clone, they all read the same accounts. So you only need to set up your accounts once.

Setting Up Accounts in npx Mode

If you run the server via npx (no clone), you have two ways to add accounts:

Option A — Run the setup wizard directly via npx (no install needed):

npx -p imap-mcp-server imap-setup

This launches the same web-based wizard described below and writes to ~/.imap-mcp/accounts.json, which your npx-configured MCP server then picks up automatically.

Option B — Add accounts straight from your AI client:

Once the MCP server is configured, just ask your assistant to add an account — it uses the imap_add_account tool. For example:

"Add my IMAP account: host imap.gmail.com, port 993, user [email protected], password …"

No separate setup step required.

Web-Based Setup Wizard (Recommended)

After installation, run the setup wizard:

npm run setup

Or if installed globally:

imap-setup

Or directly via npx without installing:

npx -p imap-mcp-server imap-setup

This will:

1. Start a local web server
2. Open your browser to the setup wizard
3. Guide you through adding email accounts with pre-configured settings

The wizard listens on 127.0.0.1 only, so nothing else on your network can reach it.

Running the wizard on another machine (server, NAS, VM)

Recommended: SSH tunnel. The wizard stays on loopback, and the connection is encrypted:

ssh -L 3000:localhost:3000 my-server      # then, on the server:
imap-setup --no-open

Open http://localhost:3000 in your local browser.

Alternative: bind to the network. Pass --host (or set IMAP_MCP_BIND):

imap-setup --host 0.0.0.0 --no-open

The wizard then requires an access token and prints a URL containing it, e.g. http://my-server:3000/?token=…. Open that URL; the token is exchanged for a session cookie and removed from the address bar. Requests without the token are refused, and so are cross-origin requests. Scripts can send Authorization: Bearer <token> instead. To use a fixed token rather than a random one per start, set IMAP_MCP_WIZARD_TOKEN (at least 16 characters); it is then not printed.

The connection is plain HTTP, so anyone who can read your network traffic can see the token and the passwords you enter. Use this only on networks you trust, and prefer the SSH tunnel otherwise.

Overriding Credentials via Environment Variables

You can override the username and password of an already-configured account at runtime with environment variables — useful when you inject secrets from a password manager or CI system instead of storing them in accounts.json.

The variables are keyed by the account name, uppercased with every non-alphanumeric character replaced by _. For an account named Work Gmail (key WORK_GMAIL):

Notes:

• Overrides apply only to existing accounts; if no account's normalized name matches, the variable is ignored.
• They are applied in memory only — nothing is written back to accounts.json, and the values are used as-is (not re-encrypted).
• Variables are consumed at startup: on server start they are captured into an AES-256-encrypted in-memory cache and removed from process.env, so the plaintext secret does not linger in the environment (where it could leak to child processes or diagnostics). Set them before launching the server.

The setup wizard integrates with this: each credential field (IMAP password, IMAP username, SMTP username, SMTP password) has a "Do not save to config; set later using an environment variable" checkbox. When ticked, the value you enter is still used to test the connection, but it is not written to accounts.json — the wizard shows the exact variable name to export, and the account picks the credential up from that variable at runtime.

• SMTP variables take effect only when the account already has an SMTP config.
• Each variable takes effect independently; set only the ones you need.

If the variable is missing, the account still holds the empty placeholder the wizard wrote. Rather than dialing out with a blank credential — which providers answer with a generic authentication failure that looks exactly like a wrong password — the server refuses the connection and names what to set:

Account "Work Gmail" has IMAP credentials marked as environment-managed, but
this variable was not set when the server started:
IMAP_MCP_ACCOUNT_WORK_GMAIL_IMAP_PASSWORD. Set it and restart the server, or
store the credentials on the account via imap_update_account.

Because the variables are read once at startup, setting one in an already-running shell has no effect until the server is restarted.

Supported Email Providers

The setup wizard includes pre-configured settings for:

• Gmail / Google Workspace
• Microsoft Outlook / Hotmail / Live
• Yahoo Mail
• Apple iCloud Mail
• GMX
• WEB.DE
• IONOS (1&1)
• ProtonMail (with Bridge)
• Fastmail
• Zoho Mail
• AOL Mail
• mailbox.org
• Posteo
• Custom IMAP servers

Configuration

Claude Code (CLI)

Option A — via npx (no clone/build needed)

claude mcp add imap -- npx -y imap-mcp-server

This always runs the latest published version and requires no local build.

Option B — from a local clone

If you use Claude Code in the terminal, add the MCP server with a single command:

Step 1: Make sure you have built the project first (see Manual Installation).

Step 2: Run this command in your terminal:

claude mcp add imap -- node /absolute/path/to/imap-mcp-server/dist/index.js

Important: Replace /absolute/path/to/imap-mcp-server with the actual path where you cloned the repository. For example:

# macOS/Linux example:
claude mcp add imap -- node /Users/yourname/imap-mcp-server/dist/index.js

# Windows example:
claude mcp add imap -- node C:\Users\yourname\imap-mcp-server\dist\index.js

Step 3: Verify it was added:

claude mcp list

You should see imap in the list of configured MCP servers. That's it — the IMAP tools are now available in your Claude Code sessions.

Tip: If you want to remove the server later, run:

claude mcp remove imap

Claude Desktop (GUI App)

Add the IMAP MCP server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Option A — via npx (recommended, no clone/build needed):

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

Option B — from a local clone:

{
  "mcpServers": {
    "imap": {
      "command": "node",
      "args": ["/path/to/imap-mcp-server/dist/index.js"],
      "env": {}
    }
  }
}

Restricting tool access (read-only mode / allowlist)

By default all tools are exposed. You can restrict which tools the agent sees using two environment variables (set them under the env key of your MCP config). This is useful when you want to give an assistant read-only access to a mailbox, or expose only a hand-picked subset of tools.

Example — read-only access:

{
  "mcpServers": {
    "imap": {
      "command": "npx",
      "args": ["-y", "imap-mcp-server"],
      "env": { "IMAP_MCP_READ_ONLY": "true" }
    }
  }
}

Example — explicit allowlist:

{
  "mcpServers": {
    "imap": {
      "command": "npx",
      "args": ["-y", "imap-mcp-server"],
      "env": { "IMAP_MCP_ENABLED_TOOLS": "imap_search_emails,imap_get_email,imap_get_latest_emails" }
    }
  }
}

The read-only subset is: imap_list_accounts, imap_connect, imap_disconnect, imap_test_account, imap_search_emails, imap_get_email, imap_get_latest_emails, imap_download_attachment, imap_find_thread_messages, imap_find_email_by_message_id, imap_list_folders, imap_folder_status, imap_get_unread_count, imap_check_spam, imap_domain_stats, imap_list_spam_domains.

Usage

Once configured, the IMAP MCP server provides the following tools in Claude:

Choosing an account. For the email and folder tools, accountId is optional and backward-compatible. You may instead pass accountName, and if you only have a single account configured you can omit both — that account is used by default. With multiple accounts and no selector, the tool returns a clear error listing your options (imap_list_accounts).

Account Management

• imap_add_account: Add a new IMAP account

  Parameters:
  - name: Friendly name for the account
  - host: IMAP server hostname
  - port: Server port (default: 993)
  - user: Username
  - password: Password
  - tls: Use TLS/SSL (default: true)
  - allowStartTLS: When tls is false, set to false to also disable the
      opportunistic STARTTLS upgrade imapflow otherwise attempts whenever the
      server advertises it (validating the cert against `host` regardless of
      `tls`). Needed for providers that advertise STARTTLS on a hostname
      covered only by a shared/wildcard cert. Defaults to true.
  - sentFolder: Explicit Sent-folder name for sent-mail copies, e.g. "Gesendet"
      (optional — only needed when the server has no \Sent SPECIAL-USE folder
      and auto-detection fails)
  - defaultBcc: Optional BCC address(es) applied automatically to every
      outbound send, reply, forward, and draft for this account. Merged with
      any per-call `bcc` (duplicates removed case-insensitively)
  - allowedFrom: Optional list of additional sender identities permitted in
      outbound `From` headers. The account email and login are always allowed
  

• imap_update_account: Update an existing account (fix SMTP settings, rename, etc.)

  Parameters:
  - accountId: ID of the account to update
  - name, host, port, user, password, tls, allowStartTLS, email: IMAP fields (all optional)
  - smtpHost, smtpPort, smtpSecure, smtpUser, smtpPassword: SMTP fields (optional)
  - saveToSent: Save sent emails to the Sent folder (optional)
  - sentFolder: Explicit Sent-folder override (optional). Pass an empty string
      to clear the override and re-enable auto-detection
  - defaultBcc: Optional default BCC address(es) (optional). Pass an empty
      string to clear
  - allowedFrom: Optional list of additional sender identities. Pass an empty
      array to clear
  

allowedFrom is an application-level guardrail, not a hard security boundary: an agent with access to imap_update_account can change the allowed identities. The SMTP server must enforce the actual sender authorization policy. Sender mailbox addresses are matched case-insensitively; the supplied display name and address casing are preserved in the outbound From header. This applies to sending, drafts, replies, and forwards.

• imap_list_accounts: List all configured accounts

• imap_remove_account: Remove an account

  Parameters:
  - accountId: ID of the account to remove
  

• imap_connect: Connect to an account

  Parameters:
  - accountId OR accountName: Account identifier
  

• imap_disconnect: Disconnect from an account

  Parameters:
  - accountId: Account to disconnect
  

Email Operations

• imap_search_emails: Search for emails

  Parameters:
  - accountId: Account ID
  - folder: Folder name (default: INBOX; ignored when searchAllFolders is true)
  - searchAllFolders: Search across ALL folders at once (default: false).
      Skips Trash/Spam/Drafts and non-selectable folders by default. Use when a
      message may have been filed/moved/archived and you don't know its folder.
  - includeTrash, includeSpam, includeDrafts: Opt those noisy folders back into
      a searchAllFolders run (default: false each)
  - from, to, subject, body: Search criteria
  - since, before: Date filters
  - seen, flagged: Status filters
  - keywords: Match messages with ANY of these custom keywords (server-side OR).
      Read a mailbox's available custom keywords from `imap_folder_status`'s
      `customKeywords` field first.
  - unKeywords: Exclude messages with ANY of these custom keywords (result has
      NONE of them). Same keyword source as `keywords`.
  - limit: Max results (default: 50)
  - includeBody: Include parsed message body in the response (default: false).
      Fetches the RFC822 source once and parses it with mailparser, so you get
      uid + body in a single tool call instead of paying the N+1 cost of one
      `imap_get_email` per match. Body is rendered per `bodyFormat` and capped
      at `bodyMaxLength` per field.
  - bodyFormat: How to render the body when `includeBody` is true — `markdown`
      (default, clean Markdown via Turndown), `text`, `html`, or `auto`.
  - bodyMaxLength: Per-field cap when `includeBody` is true (default: 10000).
  

  With searchAllFolders, results include a folder field per message plus foldersSearched, and any folder that failed to open is reported in foldersErrored (so a 0-result answer is never silently incomplete).

  includeBody is honored in the single-folder path only. For a cross-folder sweep the lightweight header shape is preserved by design — pulling RFC822 source for every match across many folders would multiply bandwidth and parse cost. Follow up with imap_get_email for the specific uids whose bodies you need.

  On some servers a "flagged"/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, check each result's customKeywords field before concluding a message is or isn't flagged.

• imap_get_email: Get full email content

  Parameters:
  - accountId: Account ID
  - folder: Folder name
  - uid: Email UID
  - maxContentLength: Max characters for text/html body (default: 10000)
  - includeAttachmentText: Include text attachment previews (default: true)
  - maxAttachmentTextChars: Max characters per text attachment (default: 100000)
  

Folder Operations

• imap_list_folders: List all folders

  Parameters:
  - accountId: Account ID
  

  Each folder includes its attributes (raw IMAP LIST flags) and, when the server advertises it, specialUse — the RFC 6154 role (\Sent, \Drafts, \Trash, \Junk, \Archive) that identifies a folder independent of its localized display name (e.g. "Gesendet" carries specialUse: "\Sent").

• imap_folder_status: Get folder information

  Parameters:
  - accountId: Account ID
  - folder: Folder name
  
  Returns:
  - messages: { total, new, unseen } — from IMAP STATUS
  - uidvalidity, uidnext
  - flags, permanentFlags: string arrays
  - customKeywords: the mailbox's non-system keywords, usable as the
      `keywords` / `unKeywords` input of imap_search_emails
  

• imap_create_folder: Create a new IMAP folder/mailbox. Most servers also create any missing parent folders. Returns success even if the folder already exists.

  Parameters:
  - accountId: Account ID
  - folder: Full folder path to create (e.g. "Archives/2026/2026-05" or "INBOX.Archive")
  

• imap_get_unread_count: Count unread emails

  Parameters:
  - accountId: Account ID
  - folders: Specific folders (optional)
  

Security

• Credentials are encrypted using AES-256-CBC encryption
• Encryption keys are stored separately in ~/.imap-mcp/.key
• Account configurations are stored in ~/.imap-mcp/accounts.json
• The store directory, .key, and accounts.json are written owner-only (0700/0600) so other local users cannot read the key or the credentials
• The web setup wizard's HTTP API never returns stored passwords to the browser
• Downloaded attachments are confined to the downloads directory; sender-supplied filenames cannot write outside it
• Never commit or share your encryption key or account configurations

Development

Running in Development Mode

npm run dev

Building

npm run build

Project Structure

src/
├── index.ts           # MCP server entry point
├── services/
│   ├── imap-service.ts    # IMAP connection management
│   ├── smtp-service.ts    # SMTP service for sending emails
│   └── account-manager.ts # Account configuration
├── tools/
│   ├── index.ts          # Tool registration
│   ├── account-tools.ts  # Account management tools
│   ├── email-tools.ts    # Email operation tools (including send/reply/forward)
│   └── folder-tools.ts   # Folder operation tools
└── types/
    └── index.ts          # TypeScript type definitions

Example Usage in Claude

1. Add an account: "Add my Gmail account with username [email protected]"

2. Check new emails: "Show me the latest 5 emails from my Gmail account"

3. Search emails: "Search for emails from [email protected] in the last week"

4. Send an email: "Send an email to [email protected] with subject 'Project Update'"

5. Reply to emails: "Reply to the latest email from my boss"

6. Forward emails: "Forward the email with subject 'Meeting Notes' to [email protected]"

7. Move an email: "Move the invoice email from INBOX to my Taxes folder"

8. Manage folders: "List all folders in my email account and show unread counts"

Troubleshooting

Connection Issues

• Ensure your IMAP server settings are correct
• Check if your email provider requires app-specific passwords
• Verify that IMAP is enabled in your email account settings
• For sending emails, ensure your account has SMTP access enabled

Recipients arriving as ["[email protected]","[email protected]"]

to, cc, bcc, references and uid accept either a single value or an array. In JSON Schema that is an anyOf, and some MCP clients drop the anyOf before showing the schema to the model — the field then looks untyped or string-typed, and the client serializes the model's array into a string. The server used to pass that string straight to nodemailer, which folded the literal [ and ] into the first and last address, so every recipient was rejected by the receiving mail server (issue #127).

The server now detects a stringified array and restores it, both when validating tool input and again before composing the message, and logs a warning to stderr naming the field. Nothing needs to change on your side. If you want to bypass the client behavior entirely, pass recipients as one comma-separated string: "Alice <[email protected]>, Bob <[email protected]>".

Search returns nothing although the folder has mail (Strato)

Since mid-2026 Strato's IMAP server (imap.strato.com) answers every SEARCH command with an empty result, while FETCH still works (issue #138). The server detects this: when a SEARCH comes back empty for a folder that is not empty and SEARCH ALL is empty as well, it fetches the envelopes and applies the criteria itself. imap_search_emails, imap_find_thread_messages, the unread counts and the spam analysis keep working; imap_get_latest_emails never needed SEARCH.

Limits of the fallback:

• It is slower — every envelope of the folder is downloaded per search.
• A body search downloads and parses each remaining candidate, so it is refused above 2000 candidates; narrow it with since/from/subject.
• Deleting tools (imap_bulk_delete_by_search, imap_delete_spam, imap_delete_by_domain) do not use it and return an error instead. Find the messages with imap_search_emails and delete their UIDs with imap_bulk_delete.

SMTP Configuration

The server automatically configures SMTP settings based on your IMAP provider. If you need custom SMTP settings, you can specify them when adding an account:

{
  "smtp": {
    "host": "smtp.example.com",
    "port": 587,
    "secure": false
  }
}

Common IMAP Settings

• Gmail:

  • Host: imap.gmail.com
  • Port: 993
  • Requires app-specific password

• Outlook/Hotmail:

  • Host: outlook.office365.com
  • Port: 993

• Yahoo:

  • Host: imap.mail.yahoo.com
  • Port: 993
  • Requires app-specific password

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.