imap-mcp-server

IMAP MCP 服务

功能强大的 Model Context Protocol（MCP）服务，可无缝集成 IMAP 邮件，并提供安全的账户管理和连接池。

功能

• 🔐 安全的账户管理：使用 AES-256 加密存储凭据
• 🚀 连接池：高效管理 IMAP 连接
• 📧 全面的邮件操作：搜索、读取、移动、标记、删除和批量删除邮件
• ✉️ 发送邮件：通过 SMTP 发送、回复和转发邮件
• 📁 文件夹管理：列出文件夹、检查状态、获取未读邮件数
• 🔄 支持多个账户：同时管理多个 IMAP 账户
• 🛡️ 类型安全：使用 TypeScript 构建，确保可靠性
• 🌐 网页设置向导：使用预设服务商配置，轻松设置账户
• 📱 支持 15+ 个电子邮件服务商：预配置 Gmail、Outlook、Yahoo 等服务商的设置
• 🔗 自动配置 SMTP：根据 IMAP 服务商自动设置 SMTP

安装

需要 Node.js 22.12 或更高版本。 Node 18 和 Node 20 均已结束生命周期，且此软件包的若干依赖不再支持它们。使用 node --version 检查当前版本。

通过 npx 运行（无需安装）

发布到 npm 后，无需克隆或构建任何内容，即可直接运行服务——npx 会下载预构建的软件包并运行：

npx -y imap-mcp-server

这是在 MCP 客户端中使用此服务最简单的方式（可在配置中查看可直接粘贴的 npx 配置）。

快速安装（推荐）

macOS/Linux：

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

Windows（以管理员身份运行 PowerShell）：

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

手动安装

1. 克隆仓库：

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

2. 安装依赖：

npm install

3. 构建项目：

npm run build

账户设置

账户以加密形式存储在 ~/.imap-mcp/accounts.json 中。此文件由所有运行模式共用——无论你通过 npx、全局安装还是本地克隆启动服务，它们都会读取同一份账户数据。因此，你只需设置一次账户。

在 npx 模式下设置账户

如果你通过 npx 运行服务（未克隆仓库），可以通过两种方式添加账户：

选项 A — 直接通过 npx 运行设置向导（无需安装）：

npx -p imap-mcp-server imap-setup

这会启动下文所述的同一网页向导，并将数据写入 ~/.imap-mcp/accounts.json，之后使用 npx 配置的 MCP 服务会自动读取该文件。

选项 B — 直接从 AI 客户端添加账户：

配置好 MCP 服务后，只需让助手添加账户即可——它会使用 imap_add_account 工具。例如：

“添加我的 IMAP 账户：主机 imap.gmail.com，端口 993，用户 [email protected]，密码……”

无需单独设置。

网页设置向导（推荐）

安装后，运行设置向导：

npm run setup

如果是全局安装，也可以运行：

imap-setup

也可以直接通过 npx 运行，无需安装：

npx -p imap-mcp-server imap-setup

此操作将：

1. 启动本地 Web 服务
2. 在浏览器中打开设置向导
3. 引导你使用预配置的设置添加电子邮件账户

向导仅监听 127.0.0.1，因此网络上的其他设备无法访问。

在另一台机器上运行向导（服务器、NAS、VM）

推荐：SSH 隧道。 向导仍绑定到回环地址，连接也会加密：

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

在本地浏览器中打开 http://localhost:3000。

替代方案：绑定到网络。 传入 --host（或设置 IMAP_MCP_BIND）：

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

此时，向导需要访问令牌，并会打印一个包含令牌的 URL，例如： http://my-server:3000/?token=…。打开该 URL；令牌会被交换为会话 Cookie，并从地址栏中移除。没有令牌的请求会被拒绝，跨域请求也会被拒绝。脚本也可以改用 Authorization: Bearer <token>。如需使用固定令牌，而不是每次启动时生成随机令牌，请设置 IMAP_MCP_WIZARD_TOKEN（至少 16 个字符）；设置后不会打印该令牌。

连接使用纯 HTTP，因此任何能够读取网络流量的人都能看到令牌和你输入的密码。仅在可信网络中使用此方式，其他情况下优先使用 SSH 隧道。

变量	默认值	含义
IMAP_MCP_BIND	127.0.0.1	向导绑定的地址（--host 优先）
IMAP_MCP_WIZARD_TOKEN	每次启动时随机生成	绑定到回环地址以外时使用的访问令牌
PORT	3000	npm run web 使用的端口（imap-setup 使用 --port）

通过环境变量覆盖凭据

你可以在运行时通过环境变量覆盖已配置账户的用户名和密码——如果你从密码管理器或 CI 系统注入密钥，而不是将其存储在 accounts.json 中，这会很有用。

环境变量根据账户名称命名：将名称转为大写，并把所有非字母数字字符替换为 _。例如，账户名为 Work Gmail（键名为 WORK_GMAIL）：

变量	覆盖内容
IMAP_MCP_ACCOUNT_WORK_GMAIL_IMAP_USERNAME	IMAP 用户名（user）
IMAP_MCP_ACCOUNT_WORK_GMAIL_IMAP_PASSWORD	IMAP 密码
IMAP_MCP_ACCOUNT_WORK_GMAIL_SMTP_USERNAME	SMTP 用户名（smtp.user）
IMAP_MCP_ACCOUNT_WORK_GMAIL_SMTP_PASSWORD	SMTP 密码

注意：

• 覆盖仅适用于已有账户；如果没有账户的标准化名称与之匹配，该变量将被忽略。
• 覆盖值仅在内存中生效——不会写回 accounts.json，并且会按原样使用（不会重新加密）。
• 变量会在启动时读取：服务器启动时，会将其捕获到 AES-256 加密的内存缓存中，并从 process.env 中移除，因此明文密钥不会留在环境中（否则可能泄露给子进程或诊断信息）。请在启动服务器前设置这些变量。

设置向导也支持此功能：每个凭据字段（IMAP 密码、IMAP 用户名、SMTP 用户名、SMTP 密码）都有一个 “不保存到配置中；稍后通过环境变量设置” 复选框。勾选后，你输入的值仍会用于测试连接，但不会写入 accounts.json——向导会显示要导出的确切变量名，账户将在运行时从该变量中读取凭据。

• 只有账户已有 SMTP 配置时，SMTP 变量才会生效。
• 每个变量独立生效；只设置需要的变量即可。

如果缺少该变量，账户仍会保留向导写入的空占位值。服务器不会使用空凭据尝试连接——服务提供商返回的通用身份验证失败信息看起来与密码错误完全相同。相反，服务器会拒绝连接，并指出需要设置什么：

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.

由于变量只会在启动时读取，因此在已运行的 Shell 中设置变量不会生效，必须重启服务器。

支持的电子邮件服务提供商

设置向导包含以下预配置设置：

• Gmail / Google Workspace
• Microsoft Outlook / Hotmail / Live
• Yahoo Mail
• Apple iCloud Mail
• GMX
• WEB.DE
• IONOS (1&1)
• ProtonMail（搭配 Bridge）
• Fastmail
• Zoho Mail
• AOL Mail
• mailbox.org
• Posteo
• 自定义 IMAP 服务器

配置

Claude Code（CLI）

选项 A — 通过 npx（无需克隆或构建）

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

这始终会运行最新发布的版本，无需本地构建。

选项 B — 从本地克隆运行

如果你在终端中使用 Claude Code，只需运行一条命令即可添加 MCP 服务：

步骤 1： 确保已先构建项目（请参阅手动安装）。

步骤 2： 在终端中运行此命令：

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

重要： 将 /absolute/path/to/imap-mcp-server 替换为你克隆仓库的实际路径。例如：

# macOS/Linux 示例：
claude mcp add imap -- node /Users/yourname/imap-mcp-server/dist/index.js

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

步骤 3： 验证是否已添加：

claude mcp list

你应该会在已配置的 MCP 服务列表中看到 imap。就是这样 — IMAP 工具现已可在你的 Claude Code 会话中使用。

提示： 如果之后想移除该服务，请运行：

claude mcp remove imap

Claude Desktop（GUI 应用）

将 IMAP MCP 服务添加到 Claude Desktop 配置文件中：

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

选项 A — 通过 npx（推荐，无需克隆或构建）：

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

选项 B — 从本地克隆运行：

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

限制工具访问（只读模式／允许列表）

默认情况下会公开所有工具。你可以使用两个环境变量限制 Agent 可用的工具 （在 MCP 配置的 env 键下设置）。如果你想向助手授予邮箱的只读访问权限， 或只公开经过挑选的工具子集，这会很有用。

变量	效果
IMAP_MCP_READ_ONLY	值为真（1、true、yes、on）时，只注册安全的只读工具 — 搜索、读取、列出文件夹、未读邮件计数和垃圾邮件分析。不会公开发送邮件、删除／移动邮件、更改标记或编辑账户的工具。
IMAP_MCP_ENABLED_TOOLS	以逗号分隔的工具名称允许列表 — 只注册这些工具。名称不区分大小写，且 imap_ 前缀可省略（search_emails ≡ imap_search_emails）。设置后，此变量优先于 IMAP_MCP_READ_ONLY。

示例 — 只读访问：

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

示例 — 显式允许列表：

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

只读工具子集包括：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。

使用方法

配置完成后，IMAP MCP 服务会在 Claude 中提供以下工具：

选择账户。 对于邮件和文件夹工具，accountId 是可选的，并向后兼容。你也可以传入 accountName；如果只配置了一个账户，则两者都可以省略 — 默认使用该账户。配置了多个账户但未指定账户时，工具会返回一条清晰的错误信息并列出可选项（imap_list_accounts）。

账户管理

• imap_add_account：添加新的 IMAP 账户

  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：更新现有账户（修正 SMTP 设置、重命名等）

  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 是应用层的防护措施，并非严格的安全边界： 有权访问 imap_update_account 的 Agent 可以更改允许使用的身份。 SMTP 服务器必须强制执行实际的发件人授权策略。发件人邮箱地址匹配时不区分大小写；提供的显示名称和地址大小写会在发出的 From 标头中保留。此规则适用于发送邮件、草稿、回复和转发。

• imap_list_accounts：列出所有已配置的账户

• imap_remove_account：移除账户

  Parameters:
  - accountId: ID of the account to remove
  

• imap_connect：连接到账户

  Parameters:
  - accountId OR accountName: Account identifier
  

• imap_disconnect：断开与账户的连接

  Parameters:
  - accountId: Account to disconnect
  

邮件操作

• imap_search_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).
  

  使用 searchAllFolders 时，结果会为每封邮件包含一个 folder 字段，并包含 foldersSearched；任何无法打开的文件夹都会列在 foldersErrored 中（因此 0 条结果不会在未提示的情况下遗漏内容）。

  只有在单文件夹路径中才会应用 includeBody。跨文件夹扫描会有意保留轻量级标头结构 — 对多个文件夹中的每条匹配结果都提取 RFC822 源内容，会显著增加带宽消耗和解析开销。请对需要正文的特定 uid 调用 imap_get_email 获取后续内容。

  在某些服务器上，“已标记”/星标邮件会带有自定义关键字（例如 Open-Xchange 的颜色标签或 Apple 的 $MailFlagBit*），而不是 \Flagged 系统标志，也可能同时带有两者 — 执行任何已标记邮件搜索后，请检查每条结果的 customKeywords 字段，再判断邮件是否已标记。

• imap_get_email：获取完整邮件内容

  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)
  

• imap_get_latest_emails：获取近期邮件

  Parameters:
  - accountId: Account ID
  - folder: Folder name (default: INBOX)
  - count: Number of emails (default: 10)
  - includeBody: Include parsed message body (default: false). Same semantics
      as the `includeBody` option on `imap_search_emails` — one round-trip
      instead of N×`imap_get_email`.
  - bodyFormat: `markdown` (default), `text`, `html`, or `auto`.
  - bodyMaxLength: Per-field cap (default: 10000).
  

• imap_mark_as_read/unread：更改邮件的已读状态

  Parameters:
  - accountId: Account ID
  - folder: Folder name
  - uid: Email UID, OR an array of UIDs to flag in one call. Batch uses a
      single IMAP STORE so the operation is atomic at the server level — all
      UIDs are flagged, or none. Useful when triaging many messages at once.
  

• imap_flag_email/unflag_email：为邮件加星标/取消星标（设置或清除 IMAP \Flagged 系统标志 — 在 Gmail 和 Apple Mail 中显示为“星标”）。某些服务器/客户端（Open-Xchange、Apple Mail）在标记邮件时还会设置单独的自定义关键字（例如 $cl_N、$MailFlagBit*）；取消标记只会清除 \Flagged，因此，如果邮件仍显示为已标记，请通过 imap_get_email 检查 customKeywords，并使用 imap_remove_keyword 清除该关键字。

  Parameters:
  - accountId: Account ID
  - folder: Folder name
  - uid: Email UID
  

• imap_add_keyword/remove_keyword：为邮件设置或清除任意自定义（非系统）IMAP 关键字/标签，并原样传递（例如 Open-Xchange 的 $cl_1..$cl_10 等提供商颜色标签、Apple Mail 的 $MailFlagBit0..$MailFlagBit2，或任何其他自定义关键字）。不允许使用反斜杠开头的系统标志（例如 \Flagged、\Seen、\Deleted）— 请使用专用的标记/已读工具。并非所有服务器都允许更改自定义关键字（请参阅邮箱的 PERMANENTFLAGS）；如果服务器拒绝或默默忽略更改，则调用会失败，而不会报告成功。

  Parameters:
  - accountId: Account ID
  - folder: Folder name
  - uid: Email UID
  - keyword: IMAP keyword to set/remove (e.g. "$cl_3")
  

• imap_delete_email：删除邮件

  Parameters:
  - accountId: Account ID
  - folder: Folder name
  - uid: Email UID
  

• imap_move_email：将邮件从一个文件夹移至另一个文件夹

  Parameters:
  - accountId: Account ID
  - folder: Source folder name (default: INBOX)
  - uid: Email UID, OR an array of UIDs to move in one call. Batch moves are
      attributed per-uid in the response (`results[]` with per-uid `uidMap`
      and any errors). Single-uid calls return the legacy response shape.
  - targetFolder: Destination folder name
  - createDestinationIfMissing: Create the destination folder if it does not exist (default: false)
  

• imap_find_thread_messages：查找收件箱中的邮件，这些邮件与已归入其他文件夹的邮件属于同一对话线程。使用 RFC 3501 HEADER 搜索 In-Reply-To 和 References — 适用于任何 IMAP 服务器。

  Parameters:
  - accountId: Account ID
  - sourceFolder: Folder containing the already-sorted thread messages
  - searchFolder: Folder to search for related messages (default: INBOX)
  - searchReferences: Also match the References header for multi-level threads (default: true)
  - includeBody: Include parsed message body for each found thread message
      (default: false). Same semantics as the `includeBody` option on
      `imap_search_emails` — one round-trip instead of N×`imap_get_email`.
  - bodyFormat: `markdown` (default), `text`, `html`, or `auto`.
  - bodyMaxLength: Per-field cap (default: 10000).
  

• imap_download_attachment：下载邮件附件（以内嵌方式返回图片、提取 PDF 中的文本，或保存到下载目录）

  Parameters:
  - accountId: Account ID
  - folder: Folder name (default: INBOX)
  - uid: Email UID
  - filename: Attachment filename or contentId (as listed by imap_get_email; NFC/NFD
      spellings of accented characters are treated as equal, and a contentId may
      be passed with or without angle brackets)
  - savePath: Optional file path to save the attachment to
  - extractText: For PDFs, extract and return text content inline (default: true)
  

• imap_bulk_delete：通过分块处理和自动重新连接，一次删除多封邮件

  Parameters:
  - accountId: Account ID
  - folder: Folder name (default: INBOX)
  - uids: Array of email UIDs to delete
  - chunkSize: Emails to delete per batch (default: 50)
  

• imap_bulk_delete_by_search：搜索符合条件的邮件并将其全部删除

  Parameters:
  - accountId: Account ID
  - folder: Folder name (default: INBOX)
  - from, to, subject: Search criteria (optional)
  - before, since: Date filters (optional)
  - chunkSize: Emails to delete per batch (default: 50)
  - dryRun: Preview what would be deleted without deleting (default: false)
  

  至少需要一个具体条件（from、to、subject、before 或 since）。 不提供条件的调用会被拒绝，因此绝不会匹配并删除整个文件夹。在 SEARCH 异常的服务器上（参见“故障排除 → 搜索结果为空”），此工具、 imap_delete_spam 和 imap_delete_by_domain 会返回错误，而不会根据 客户端匹配结果删除邮件。

• imap_send_email：发送新邮件

  Parameters:
  - accountId: Account ID to send from
  - from: Sender identity (optional). Must match the account email/login or an
      address configured in `allowedFrom`
  - to: Recipient email address(es) — an array, or a single comma-separated string
  - subject: Email subject
  - text: Plain text content (optional)
  - html: HTML content (optional)
  - cc: CC recipients (optional)
  - bcc: BCC recipients (optional)
  - replyTo: Reply-to address (optional)
  - attachments: Array of attachments (optional)
    - filename: Attachment filename
    - content: Base64 encoded content; provide exactly one of `content` or `path`
    - path: Readable local file path to attach; provide exactly one of `path` or `content`
    - contentType: MIME type (optional; detected from the filename extension when omitted)
    - contentDisposition: "attachment" (default) or "inline" — use "inline" for images shown in the HTML body via cid:
    - cid: Content-ID for inline attachments; must match the `cid:` value used in an `<img src="cid:...">` tag in `html`
  - dryRun: Validate attachments and compose MIME without sending or saving to Sent (optional, default: false)
  

  联系 SMTP 之前会先验证附件。无效的 base64、无法读取的路径、缺少文件名、 来源不明确，以及缺少 cid 的内联附件都会立即导致失败。发送成功和试运行 均会返回 attachmentCount 和安全的 attachmentDiagnostics：文件名、MIME 类型、大小、来源、处置方式和 cid。诊断信息不包含字节数据、原始 MIME 或 本地文件路径。

  对于大文件，请先使用 imap_upload_file 上传，并传入它返回的本地 path； 对于内联图片，请设置 contentDisposition: "inline" 和相应的 cid。

  发送后，邮件副本会保存到帐户的“已发送”文件夹（除非该帐户禁用了 saveToSent）。文件夹的解析顺序为：帐户的 sentFolder 覆盖项 → 服务器的 \Sent SPECIAL-USE 标志 → 已知的本地化名称列表（"Sent"、"Gesendet"、 "Éléments envoyés" 等）。响应会报告结果：savedToSent（布尔值）、 sentFolder（所用文件夹）；如果保存失败，还会提供说明原因的 sentSaveError，而不会静默失败。imap_reply_to_email 和 imap_forward_email 也适用同样的规则。

  如果帐户配置了 defaultBcc，发送、回复、转发和保存草稿时都会密送这些 地址（与每次调用的 bcc 合并，并以不区分大小写的方式去重）。草稿和 “已发送”文件夹副本中会保留 Bcc 标头，以便邮件客户端显示该信息。

• imap_save_draft：将邮件保存为草稿（不发送）。接受与 imap_send_email 相同的字段，另加 inReplyTo、references，以及可选的 Drafts 文件夹 folder 覆盖项。

• imap_reply_to_email：回复现有邮件

  Parameters:
  - accountId: Account ID
  - folder: Folder containing the original email
  - uid: UID of the email to reply to
  - text: Plain text reply content (optional)
  - html: HTML reply content (optional)
  - replyAll: Reply to all recipients (default: false)
  - bcc: BCC recipients (optional; merged with account defaultBcc)
  - attachments: Array of attachments (optional, same shape as imap_send_email, including contentDisposition/cid for inline images)
  

• imap_forward_email：转发现有邮件

  Parameters:
  - accountId: Account ID
  - folder: Folder containing the original email
  - uid: UID of the email to forward
  - to: Forward to email address(es)
  - text: Additional text to include (optional)
  - bcc: BCC recipients (optional; merged with account defaultBcc)
  - includeAttachments: Include original attachments (default: true)
  

文件夹操作

• imap_list_folders：列出所有文件夹

  Parameters:
  - accountId: Account ID
  

  每个文件夹都包含其 attributes（原始 IMAP LIST 标志）；如果服务器公布了 specialUse，也会包含该字段——即 RFC 6154 角色（\Sent、\Drafts、 \Trash、\Junk、\Archive），可用于识别文件夹，而不依赖其本地化显示 名称（例如，"Gesendet" 带有 specialUse: "\Sent"）。

• imap_folder_status：获取文件夹信息

  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：创建新的 IMAP 文件夹/邮箱。大多数服务器也会创建所有缺失的父文件夹。即使文件夹已存在，也会返回成功。

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

• imap_get_unread_count：统计未读邮件

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

安全

• 凭据使用 AES-256-CBC 加密
• 加密密钥单独存储在 ~/.imap-mcp/.key
• 帐户配置存储在 ~/.imap-mcp/accounts.json
• 存储目录、.key 和 accounts.json 均仅允许所有者访问 （0700/0600），以防其他本地用户读取密钥或凭据
• Web 设置向导的 HTTP API 不会向浏览器返回已存储的密码
• 下载的附件仅限保存到下载目录；发件人提供的文件名无法将文件写入该目录之外
• 切勿提交或分享加密密钥或帐户配置

开发

在开发模式下运行

npm run dev

构建

npm run build

项目结构

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

在 Claude 中的示例用法

1. 添加账户： "添加我的 Gmail 账户，用户名为 [email protected]"

2. 查看新邮件： "显示我 Gmail 账户中最新的 5 封邮件"

3. 搜索邮件： "搜索上周来自 [email protected] 的邮件"

4. 发送邮件： "给 [email protected] 发送一封主题为 'Project Update' 的邮件"

5. 回复邮件： "回复我老板发来的最新邮件"

6. 转发邮件： "将主题为 'Meeting Notes' 的邮件转发给 [email protected]"

7. 移动邮件： "将发票邮件从 INBOX 移动到我的 Taxes 文件夹"

8. 管理文件夹： "列出我邮箱账户中的所有文件夹，并显示未读邮件数"

故障排除

连接问题

• 确保 IMAP 服务设置正确
• 检查你的邮件服务提供商是否要求使用应用专用密码
• 确认已在邮箱账户设置中启用 IMAP
• 发送邮件时，确保账户已启用 SMTP 访问权限

收件人显示为 ["[email protected]","[email protected]"]

to、cc、bcc、references 和 uid 接受单个值或数组。在 JSON Schema 中，这属于 anyOf；部分 MCP 客户端会在向模型显示架构前移除 anyOf，导致字段看起来没有类型或被标记为字符串类型，客户端随后会将模型生成的数组序列化为字符串。服务器过去会将该字符串直接传递给 nodemailer，nodemailer 会把字面字符 [ 和 ] 合并到第一个和最后一个地址中，导致接收邮件服务器拒收所有收件人（问题 #127）。

现在，服务器会检测字符串化的数组并将其还原：在验证工具输入时还原一次，在撰写邮件前再还原一次，并向 stderr 输出一条注明字段名称的警告。你无需进行任何更改。如果想完全绕过客户端的这一行为，可以将收件人作为一个逗号分隔的字符串传入："Alice <[email protected]>, Bob <[email protected]>"。

文件夹中有邮件，但搜索无结果（Strato）

自 2026 年年中以来，Strato 的 IMAP 服务（imap.strato.com）对每条 SEARCH 命令都返回空结果，但 FETCH 仍然有效（问题 #138）。服务器能够检测到这一情况：当某个非空文件夹的 SEARCH 返回空结果，且 SEARCH ALL 也返回空结果时，服务器会获取邮件信封并自行应用搜索条件。imap_search_emails、imap_find_thread_messages、未读邮件数和垃圾邮件分析仍可正常工作；imap_get_latest_emails 本来就不需要使用 SEARCH。

此回退方案的限制：

• 速度较慢——每次搜索都会下载文件夹中的所有邮件信封。
• 搜索 body 时会下载并解析每个剩余候选项，因此候选项超过 2000 个时会拒绝执行；可使用 since/from/subject 缩小范围。
• 删除工具（imap_bulk_delete_by_search、imap_delete_spam、imap_delete_by_domain）不会使用此方案，而是直接返回错误。请使用 imap_search_emails 查找邮件，然后通过其 UID 使用 imap_bulk_delete 删除。

SMTP 配置

服务器会根据你的 IMAP 服务提供商自动配置 SMTP 设置。如需自定义 SMTP 设置，可在添加账户时指定：

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

常见 IMAP 设置

• Gmail：

  • 主机：imap.gmail.com
  • 端口：993
  • 需要应用专用密码

• Outlook/Hotmail：

  • 主机：outlook.office365.com
  • 端口：993

• Yahoo：

  • 主机：imap.mail.yahoo.com
  • 端口：993
  • 需要应用专用密码

许可证

MIT

贡献

欢迎贡献！请随时提交 Pull Request。