imap-mcp-server
Allows AI agents to manage Gmail accounts over IMAP, including sending, receiving, searching, replying to, and forwarding emails, as well as managing folders and drafts.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@imap-mcp-server send an email to jane@acme.com with subject 'Q3 Report' and body 'Please find the attached report.'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
imap-mcp-server(fork:收件人参数校验修复版 / fork: send-recipient validation fix)
本仓库是 nikolausm/imap-mcp-server 的修改版(fork 式再发布),基于 npm 包
imap-mcp-server@2.0.0,修复了发送邮件类工具to参数始终报-32602参数验证错误的问题。除下述修复外,其余功能与上游保持一致。This repository is a modified re-release (fork-style) of nikolausm/imap-mcp-server, based on the npm package
imap-mcp-server@2.0.0, fixing the persistent-32602input-validation error on thetoparameter of email-sending tools. Apart from the fix described below, all other functionality is identical to upstream.
一个强大的 Model Context Protocol (MCP) IMAP 邮件服务器,支持账号加密存储、连接池、邮件收发、文件夹管理、多账号,以及基于 Web 的设置向导。
A powerful Model Context Protocol (MCP) IMAP email server with encrypted account storage, connection pooling, email send/receive, folder management, multi-account support, and a web-based setup wizard.
本 fork 修复了什么 / What this fork fixes
问题 / Problem:调用 imap_send_email、imap_save_draft、imap_forward_email 等工具时,to / cc / bcc 参数始终返回 / calling tools such as imap_send_email, imap_save_draft and imap_forward_email always fails on the to / cc / bcc parameters with:
MCP error -32602: Input validation error: Invalid arguments for tool imap_send_email: Invalid input at to根因 / Root cause:addressList() 工具函数使用 z.preprocess + z.union([z.string(), z.array(z.string())])。MCP 框架将 Zod Schema 转为 JSON Schema 时,z.preprocess 没有对应表示,导致 to 字段丢失 type 定义,客户端参数校验直接失败。
The addressList() helper uses z.preprocess + z.union([z.string(), z.array(z.string())]). When the MCP framework converts the Zod schema to JSON Schema, z.preprocess has no JSON Schema equivalent, so the to field loses its type definition and client-side validation fails immediately.
修复 / Fix:将 to / cc / bcc 等参数统一改为简单的 z.string(),确保生成的 JSON Schema 含明确的 type: "string"。
The to / cc / bcc parameters are changed to a plain z.string(), ensuring the generated JSON Schema carries an explicit type: "string".
修复位置 / Where:dist/index.js(本仓库发布的是编译后的 npm 包内容;TypeScript 源码见上游仓库 / this repository ships the compiled npm package; the TypeScript source lives in the upstream repository)。
详细过程 / Details:见 docs/bug-fix-2026-09-19.md(中英对照 / bilingual)。
注意:上游有意保留“单个字符串或字符串数组”两种输入(README Troubleshooting 一节)。本 fork 为修复 schema 校验问题将参数改为仅接受字符串。如需同时保留数组输入,请先与上游讨论方案。
Note: upstream intentionally keeps both "single string or array of strings" as valid input (see the Troubleshooting section of its README). This fork narrows the parameters to a plain string in order to fix the schema-validation issue. If you need array input preserved as well, please discuss the approach with upstream first.
Related MCP server: simple-email-mcp
安装与运行 / Installation & Usage
要求 Node.js 22.12 或更新版本。/ Requires Node.js 22.12 or newer.
方式一:克隆本仓库本地运行 / Option 1: Clone and run locally
git clone https://github.com/LukeLiu2000/imap-mcp-server.git
cd imap-mcp-server
npm install # 安装运行时依赖(如需本地启动)/ install runtime deps (only if running locally)
node dist/index.js # 直接启动(dist 已包含修复)/ start directly (dist already contains the fix)方式二:作为 MCP 服务器使用 / Option 2: Use as an MCP server
在支持 MCP 的客户端(Claude Desktop、Cursor、豆包等)中配置 / configure it in an MCP-capable client (Claude Desktop, Cursor, Doubao, etc.):
{
"mcpServers": {
"imap": {
"command": "npx",
"args": ["-y", "imap-mcp-server"]
}
}
}官方 npm 包为未修复版本;本仓库的 dist 已包含修复,可直接
node dist/index.js启动本 fork。/ The official npm package is the unfixed version; this repository'sdistalready contains the fix and can be started directly withnode dist/index.js.
配置账号 / Account setup
账号信息加密存储在 ~/.imap-mcp/accounts.json,密钥在 ~/.imap-mcp/.key。/ Account credentials are stored encrypted in ~/.imap-mcp/accounts.json; the encryption key lives in ~/.imap-mcp/.key.
npx -p imap-mcp-server imap-setup # 启动 Web 设置向导 / launch the web setup wizard常用功能示例 / Example usage
添加账号 / Add account:"Add my Gmail account with username john@gmail.com"
查邮件 / Read 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 email:"Send an email to client@example.com with subject 'Project Update'"
回复 / 转发 / Reply / Forward:"Reply to the latest email from my boss"
与上游的关系 / Relationship with upstream
项目 / Item | 地址 / URL |
上游源码仓库 / Upstream source repo | |
本 fork / This fork | |
上游 npm 包 / Upstream npm package |
上游仓库欢迎贡献(Pull Request / Issue)。如果你希望此修复合入官方版本,建议先在 上游 Issues 讨论方案(注意上游有意保留数组输入)。/ Upstream welcomes contributions (Pull Requests / Issues). If you want this fix merged into the official release, it is recommended to first discuss the approach in the upstream Issues (note that upstream intentionally keeps array input support).
License / 许可证
Copyright (c) 2024 Michael Nikolaus(原始作者 / original author)
本仓库为上游项目的修改版(fork),根据 MIT 许可证条款发布,保留原始版权声明;修改部分归修改者所有。MIT 允许使用、复制、修改、发布和分发,包括商用,但须包含上述版权声明与本许可声明。/ This repository is a modified re-release (fork) of the upstream project, published under the MIT License with the original copyright notice preserved; modifications belong to their author. MIT permits use, copying, modification, publication and distribution, including commercial use, provided the above copyright notice and this permission notice are included.
Available Tools
40 toolsimap_add_accountC
Add a new IMAP account configuration
Inputs: host (required), name (required), user (required), password (required), +8 more.
imap_add_keywordA
Set an arbitrary custom (non-system) IMAP keyword/label on an email — e.g. a provider color label like Open-Xchange's $cl_1..$cl_10, Apple Mail's $MailFlagBit0..$MailFlagBit2, or an app tag such as $promotion. Unlike imap_flag_email (which only ever sets the system \Flagged flag), this passes the keyword through verbatim, but rejects backslash-prefixed system flags (e.g. \Flagged, \Seen, \Deleted) — use the dedicated flag/read tools for those. Not every IMAP server permits custom keywords (see the mailbox's PERMANENTFLAGS) — if the server rejects or silently ignores the change, this call fails rather than reporting success.
Inputs: uid (required), keyword (required), folder, accountId, +1 more.
imap_add_spam_domainA
Add a domain to the custom spam list. Emails from this domain will be flagged as spam.
Inputs: domain (required).
imap_add_whitelist_domainA
Add a domain to the whitelist. Emails from whitelisted domains will never be flagged as spam.
Inputs: domain (required).
imap_bulk_deleteB
Delete multiple emails at once with chunking and auto-reconnection. Processes deletions in batches to prevent connection timeouts.
Inputs: uids (required), folder, accountId, chunkSize, +1 more.
imap_bulk_delete_by_searchA
Search for emails matching criteria and delete them all. Useful for cleaning up spam or unwanted emails. At least one concrete criterion (from, to, subject, before, or since) is REQUIRED — a call with no criteria is refused so it can never wipe an entire folder. Supports dryRun to preview matches first.
Inputs: to, from, since, before, +6 more.
imap_check_spamA
Check emails in a folder for spam. Combines sender-domain checks (known spam/disposable domains, suspicious patterns) with deterministic raw-header analysis: bulk-mailer X-Mailer/User-Agent signatures, Precedence: bulk, DMARC/SPF/DKIM failures in Authentication-Results, and List-Unsubscribe / Reply-To domains that do not match the sender. Header checks catch scam mail from fresh, unlisted domains that pass the domain check. Returns domain-based spam, a separate list of header-flagged mails, and domain statistics.
Inputs: accountId (required), from, limit, since, +2 more.
imap_connectC
Connect to an IMAP account
Inputs: accountId, accountName.
imap_create_folderA
Create a new IMAP folder/mailbox. Most servers also create any missing parent folders (e.g. creating "Archives/2026/2026-05" auto-creates "Archives" and "Archives/2026"). Returns success even if the folder already exists.
Inputs: folder (required), accountId, accountName.
imap_delete_by_domainB
Delete all emails from a specific domain. Useful for cleaning up unwanted newsletters or spam.
Inputs: domain (required), accountId (required), dryRun, folder.
imap_delete_emailA
Delete ONE email by folder + uid (moves to Trash or expunges, server-dependent). Destructive and not easily undone — confirm the user means this specific message. To remove many at once use imap_bulk_delete (known uids) or imap_bulk_delete_by_search (by criteria, supports dryRun). To file an email away instead of deleting, use imap_move_email.
Inputs: uid (required), folder, accountId, accountName.
imap_delete_spamC
Find and delete emails from known spam/disposable email domains.
Inputs: accountId (required), limit, dryRun, folder, +1 more.
imap_disconnectB
Disconnect from an IMAP account
Inputs: accountId (required).
imap_domain_statsA
Get statistics about sender domains in a folder. Useful for identifying bulk senders or spam patterns.
Inputs: accountId (required), limit, folder, minCount.
imap_download_attachmentA
Download a single attachment from an email (folder + uid + attachment filename/contentId, as listed by imap_get_email). Images are returned inline for viewing; PDFs are saved and their text is extracted inline (extractText); other files are saved to the shared downloads directory (or savePath). Use when the user wants the actual file contents, not just the message body.
Inputs: uid (required), filename (required), folder, savePath, +3 more.
imap_find_email_by_message_idA
Locate an email by its RFC822 Message-ID across folders and return its current { folder, uid } plus basic envelope. Robust to the message having been moved or archived (IMAP UIDs are folder-relative). Pass the returned folder + uid to imap_reply_to_email or imap_get_email. Without folders, searches Gmail \All Mail when present, else INBOX → Archive → Sent → remaining folders.
Inputs: accountId (required), messageId (required), folders.
imap_find_thread_messagesA
Find messages in searchFolder that belong to the same conversation threads as messages already in sourceFolder. Useful for catching replies that arrived after a thread was sorted. Works on any IMAP server (uses RFC 3501 HEADER search on In-Reply-To and References). Set includeBody=true to also return the parsed body for each found thread message in one round-trip — avoids the N+1 cost of calling imap_get_email per thread member.
Inputs: sourceFolder (required), accountId, bodyFormat, accountName, +4 more.
imap_flag_emailA
Flag an email — sets the IMAP \Flagged system flag (shows as a star in Gmail / a flag in Apple Mail). Use this tool when a user asks to star, flag, or mark a message as important.
Inputs: uid (required), folder, accountId, accountName.
imap_folder_statusC
Get status information about a folder
Inputs: folder (required), accountId, accountName.
imap_forward_emailA
Forward an existing email (folder + uid) to new recipients, quoting the original message and headers. Optionally include the original attachments. Use when the user wants to pass an existing message on to someone else; use imap_reply_to_email instead to respond to the sender. Account defaultBcc addresses are always BCC'd when configured.
Inputs: to (required), uid (required), bcc, body, +5 more.
imap_get_emailA
Read the FULL content of a single email by its UID (body, sender/recipients, date, attachment list, optional raw headers and text-attachment previews). By default the body is returned as clean Markdown in markdownContent and raw HTML is omitted so it never crosses the boundary; set bodyFormat to "html" for the legacy raw htmlContent, or "text" for plain text only. Use after imap_search_emails or imap_get_latest_emails gives you a uid. Body text is truncated to maxContentLength to protect the context window — raise it for long messages. To fetch attachment bytes, use imap_download_attachment.
Inputs: uid (required), folder, accountId, bodyFormat, +5 more.
imap_get_latest_emailsA
Get the most recent emails from a folder, newest first. Use this for "what just came in?" / "show my latest inbox messages" when no search filter is needed. By default returns lightweight headers (uid, from, subject, date); set includeBody=true to also return the parsed body in one round-trip instead of paying the N+1 cost of calling imap_get_email per message. To filter by sender/subject/date instead, use imap_search_emails.
Inputs: count, folder, accountId, bodyFormat, +3 more.
imap_get_unread_countA
Count unread (unseen) emails per folder, plus a total. Use for "how many unread do I have?" overviews. Defaults to all folders; pass a folders list to limit scope and speed it up.
Inputs: folders, accountId, accountName.
imap_list_accountsA
List all configured IMAP accounts
Inputs: no named parameters.
imap_list_foldersA
List all folders/mailboxes for an account (names, hierarchy delimiter, attributes, RFC 6154 special-use role). Use this first to discover exact folder names before searching, moving, or creating subfolders — folder naming varies by provider (e.g. "Archive" vs "[Gmail]/All Mail" vs "INBOX.Archive"). The specialUse field ("\Sent", "\Drafts", "\Trash", "\Junk", "\Archive") identifies a folder's role independent of its localized name (e.g. "Gesendet" is the Sent folder when specialUse is "\Sent").
Inputs: accountId, accountName.
imap_list_spam_domainsA
List all known spam domains (built-in and custom).
Inputs: no named parameters.
imap_mark_as_readA
Mark one or many emails as read. Accepts a single UID or an array — pass an array to flag N messages in one IMAP STORE round-trip (useful when triaging).
Inputs: uid (required), folder, accountId, accountName.
imap_mark_as_unreadA
Mark one or many emails as unread. Accepts a single UID or an array — pass an array to flag N messages in one IMAP STORE round-trip.
Inputs: uid (required), folder, accountId, accountName.
imap_move_emailA
Move an email from one folder to another (e.g., INBOX to Taxes, or INBOX to Archive). Optionally creates the destination folder if it does not exist.
Inputs: uid (required), targetFolder (required), folder, accountId, +2 more.
imap_remove_accountB
Remove an IMAP account configuration
Inputs: accountId (required).
imap_remove_keywordA
Remove an arbitrary custom (non-system) IMAP keyword/label from an email — e.g. a provider color label like Open-Xchange's $cl_1..$cl_10, Apple Mail's $MailFlagBit0..$MailFlagBit2, or an app tag such as $promotion. Unlike imap_unflag_email (which only ever clears the system \Flagged flag), this passes the keyword through verbatim, but rejects backslash-prefixed system flags (e.g. \Flagged, \Seen, \Deleted) — use the dedicated flag/read tools for those. Not every IMAP server permits custom keywords (see the mailbox's PERMANENTFLAGS) — if the server rejects or silently ignores the change, this call fails rather than reporting success.
Inputs: uid (required), keyword (required), folder, accountId, +1 more.
imap_remove_spam_domainA
Remove a domain from the custom spam list.
Inputs: domain (required).
imap_reply_to_emailA
Reply to an existing email identified by folder + uid. Automatically sets the recipient to the original sender, prefixes the subject with "Re:", and preserves threading (In-Reply-To/References). Set replyAll to also include the original recipients. Use this instead of imap_send_email whenever the user is responding to a message already in a mailbox. Account defaultBcc addresses are always BCC'd when configured.
Inputs: uid (required), bcc, body, html, +6 more.
imap_save_draftA
Save an email as a draft in the Drafts folder (no send). Takes the same fields as imap_send_email (including account defaultBcc when configured).
Inputs: cc, to, bcc, body, +10 more.
imap_search_emailsA
Note: on some servers a 'flagged' or 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, inspect each result's customKeywords field before concluding a message is or isn't flagged — do not rely on the flagged filter alone. Search for emails matching criteria (sender, recipient, subject, body text, date range, read/flagged status). Use this to FIND messages when you know something about them but not their UID — e.g. "emails from amazon last week", "unread invoices". By default searches a single folder (INBOX). Set searchAllFolders=true to scan every mailbox at once — this catches messages filed away by rules (e.g. a receipt routed to a custom folder); Trash/Spam/Drafts are skipped unless you opt in. By default returns lightweight headers (uid, from, subject, date, and folder when searching across folders); set includeBody=true to also return the parsed body in one round-trip instead of paying the N+1 cost of calling imap_get_email per match. For the newest messages without criteria, prefer imap_get_latest_emails.
Inputs: to, body, from, seen, +18 more.
imap_send_emailA
Compose and send a NEW email via the account's SMTP server (a copy is saved to Sent unless disabled; account defaultBcc addresses are always BCC'd when configured). Use for fresh outbound messages. To respond to an existing message use imap_reply_to_email (keeps threading); to pass a message on use imap_forward_email; to store without sending use imap_save_draft. Supports to/cc/bcc, text and/or HTML, and attachments by base64 content or by file path (see imap_upload_file for large files).
Inputs: to (required), subject (required), cc, bcc, +7 more.
imap_test_accountA
Test an existing account connection without re-entering credentials. Validates IMAP connectivity and returns folder count and message count.
Inputs: accountId (required).
imap_unflag_emailA
Unflag an email — removes the IMAP \Flagged system flag (the star in Gmail, the flag in Apple Mail). Note: some servers (e.g. Open-Xchange / Network Solutions) and Apple Mail also write a separate custom keyword such as $cl_N or $MailFlagBit* when a message is flagged in their client. Removing \Flagged alone does not clear that keyword, so the message may still display as flagged. If it does, check the message's customKeywords via imap_get_email and remove the lingering label with imap_remove_keyword.
Inputs: uid (required), folder, accountId, accountName.
imap_update_accountA
Update an existing IMAP account. Useful for fixing SMTP settings without removing and re-adding the account.
Inputs: accountId (required), tls, host, name, +12 more.
imap_upload_fileA
Upload a file to the server for use as an email attachment. Returns a path that can be used with imap_send_email attachments. This allows sending large attachments without hitting context window limits. Max size: 26214400 bytes (configurable via IMAP_MAX_UPLOAD_SIZE). Uploads are auto-deleted after 86400000 ms (configurable via IMAP_UPLOAD_TTL_MS).
Inputs: content (required), filename (required), contentType.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 40 tools
Most tools target a distinct resource+action, but the deletion cluster (delete_email, bulk_delete, bulk_delete_by_search, delete_spam, delete_by_domain) and the flag/keyword cluster overlap enough to require careful reading of descriptions. An agent could easily pick the wrong delete or flag tool despite the detailed guidance.
All tools share the imap_ prefix and mostly follow a verb_noun pattern like list_accounts, send_email, and create_folder. Minor deviations such as connect, disconnect, folder_status, and delete_by_domain slightly break the pattern, but the overall naming is predictable.
With 40 tools, this server is well beyond the 16-25 'heavy' range and feels over-split. The domain is broad, but several clusters (spam management, deletion variants) could be consolidated into fewer, more coherent tools.
The tool set covers the full email lifecycle: account management, connection, search/read, send/reply/forward/draft, attachments, folder operations, flags/keywords, unread counts, and spam handling. There are no major dead ends or missing core operations for an IMAP server.
Related MCP Connectors
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over MCP.
Email: search, read, fetch attachments; attach files when the MCP client supports inputs.
Email and optional phone for AI agents: send, receive, search, draft and call over MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables reading and sending emails via IMAP and SMTP through the MCP protocol. Supports multiple email accounts and configuration via UI or environment variables.BSD 3-Clause
- AlicenseBqualityCmaintenanceEnables users to manage email accounts via IMAP/SMTP, including reading, searching, sending emails with attachments and calendar invites, all through natural language interactions with MCP-compatible clients.136 PyPI4MIT
- AlicenseNot gradedqualityBmaintenanceEnables searching, reading full conversations, and sending email across multiple IMAP/SMTP mailboxes from any MCP client, with multi-user support and per-user API tokens.MIT
- FlicenseNot gradedqualityCmaintenanceEmail capabilities for AI agents to receive, read, reply, and send through MCP.-