The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Imap MCP Server listing page.
A powerful Model Context Protocol (MCP) server that provides seamless IMAP email integration with secure account management and connection pooling.
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.
Once published to npm, you can run the server directly without cloning or building anything — npx downloads the prebuilt package and runs it:
This is the easiest way to use the server in an MCP client (see Configuration for ready-to-paste npx configs).
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.
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):
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.
After installation, run the setup wizard:
Or if installed globally:
Or directly via npx without installing:
This will:
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):
| Variable | Overrides |
|---|---|
IMAP_MCP_ACCOUNT_WORK_GMAIL_IMAP_USERNAME | IMAP username (user) |
IMAP_MCP_ACCOUNT_WORK_GMAIL_IMAP_PASSWORD | IMAP password |
IMAP_MCP_ACCOUNT_WORK_GMAIL_SMTP_USERNAME | SMTP username (smtp.user) |
IMAP_MCP_ACCOUNT_WORK_GMAIL_SMTP_PASSWORD | SMTP password |
Notes:
accounts.json, and the values are used as-is (not re-encrypted).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.
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:
Because the variables are read once at startup, setting one in an already-running shell has no effect until the server is restarted.
The setup wizard includes pre-configured settings for:
This always runs the latest published version and requires no local build.
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:
Important: Replace
/absolute/path/to/imap-mcp-serverwith the actual path where you cloned the repository. For example:
Step 3: Verify it was added:
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:
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):
Option B — from a local clone:
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.
| Variable | Effect |
|---|---|
IMAP_MCP_READ_ONLY | When truthy (1, true, yes, on), only the safe, read-only tools are registered — searching, reading, listing folders, unread counts, spam analysis. No tool that sends mail, deletes/moves messages, changes flags, or edits accounts is exposed. |
IMAP_MCP_ENABLED_TOOLS | Comma-separated allowlist of tool names — only these are registered. Names are case-insensitive and the imap_ prefix is optional (search_emails ≡ imap_search_emails). When set, it takes precedence over IMAP_MCP_READ_ONLY. |
Example — read-only access:
Example — explicit allowlist:
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.
Once configured, the IMAP MCP server provides the following tools in Claude:
Choosing an account. For the email and folder tools,
accountIdis optional and backward-compatible. You may instead passaccountName, 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).
imap_add_account: Add a new IMAP account
imap_update_account: Update an existing account (fix SMTP settings, rename, etc.)
imap_list_accounts: List all configured accounts
imap_remove_account: Remove an account
imap_connect: Connect to an account
imap_disconnect: Disconnect from an account
imap_search_emails: Search for emails
With
searchAllFolders, results include afolderfield per message plusfoldersSearched, and any folder that failed to open is reported infoldersErrored(so a 0-result answer is never silently incomplete).
includeBodyis 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 withimap_get_emailfor 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\Flaggedsystem flag — after any flagged search, check each result'scustomKeywordsfield before concluding a message is or isn't flagged.
imap_get_email: Get full email content
imap_get_latest_emails: Get recent emails
imap_mark_as_read/unread: Change email read status
imap_flag_email/unflag_email: Star/unstar an email (sets or clears the IMAP \Flagged system flag — shows as a "star" in Gmail and Apple Mail). Some servers/clients (Open-Xchange, Apple Mail) also set a separate custom keyword (e.g. $cl_N, $MailFlagBit*) when flagging; unflag only clears \Flagged, so if a message still shows as flagged, check customKeywords via imap_get_email and clear it with imap_remove_keyword.
imap_add_keyword/remove_keyword: Set or clear an arbitrary custom (non-system) IMAP keyword/label on an email, passed through verbatim (e.g. provider color labels like Open-Xchange's $cl_1..$cl_10 or Apple Mail's $MailFlagBit0..$MailFlagBit2, or any other custom keyword). Backslash-prefixed system flags (e.g. \Flagged, \Seen, \Deleted) are rejected — use the dedicated flag/read tools for those. Not every server permits custom-keyword changes (see the mailbox's PERMANENTFLAGS); if the server rejects or silently ignores the change, the call fails instead of reporting success.
imap_delete_email: Delete an email
imap_move_email: Move an email from one folder to another
imap_find_thread_messages: Find inbox messages that belong to the same conversation threads as messages already sorted into another folder. Uses RFC 3501 HEADER search on In-Reply-To and References — works on any IMAP server.
imap_download_attachment: Download an email attachment (returns images inline, extracts text from PDFs, or saves to downloads directory)
imap_bulk_delete: Delete multiple emails at once with chunking and auto-reconnection
imap_bulk_delete_by_search: Search for emails matching criteria and delete them all
At least one concrete criterion (from, to, subject, before, or since)
is required — a call with no criteria is refused, so it can never match and
delete an entire folder.
imap_send_email: Send a new email
After sending, a copy is saved to the account's Sent folder (unless
saveToSent is disabled on the account). The folder is resolved via the
account's sentFolder override → the server's \Sent SPECIAL-USE flag →
a list of known localized names ("Sent", "Gesendet", "Éléments envoyés", …).
The response reports the outcome: savedToSent (boolean), sentFolder
(the folder used), and — when the save fails — sentSaveError explaining
why, instead of failing silently. The same applies to imap_reply_to_email
and imap_forward_email.
When the account has defaultBcc configured, those address(es) are always
BCC'd on send, reply, forward, and draft (merged with any per-call bcc;
duplicates removed case-insensitively). The Bcc header is kept in the MIME
stored for drafts and Sent-folder copies so mail clients show it.
imap_save_draft: Save an email as a draft (no send). Takes the same fields as imap_send_email, plus inReplyTo, references, and an optional folder override for the Drafts folder.
imap_reply_to_email: Reply to an existing email
imap_forward_email: Forward an existing email
imap_list_folders: List all folders
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
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.
imap_get_unread_count: Count unread emails
~/.imap-mcp/.key~/.imap-mcp/accounts.json.key, and accounts.json are written owner-only
(0700/0600) so other local users cannot read the key or the credentialsAdd an account: "Add my Gmail account with username john@gmail.com"
Check new emails: "Show me the latest 5 emails from my Gmail account"
Search emails: "Search for emails from boss@company.com in the last week"
Send an email: "Send an email to client@example.com with subject 'Project Update'"
Reply to emails: "Reply to the latest email from my boss"
Forward emails: "Forward the email with subject 'Meeting Notes' to team@company.com"
Move an email: "Move the invoice email from INBOX to my Taxes folder"
Manage folders: "List all folders in my email account and show unread counts"
["a@x.com","b@y.com"]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 <alice@example.com>, Bob <bob@example.org>".
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:
Gmail:
Outlook/Hotmail:
Yahoo:
MIT
Contributions are welcome! Please feel free to submit a Pull Request.