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

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