Imap MCP Server

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

1. Install dependencies:

npm install

1. 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 me@gmail.com, 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 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:

`bash

# 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:

`bash

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,