IMAP MCP Pro

IMAP MCP Pro

一款企业级 Model Context Protocol（MCP）服务，为 IMAP 邮件集成提供可用于生产环境的支持，并具备高级可靠性功能、全面监控和安全的账户管理。

专业版 — 增强型分支，包含 1–3 级可靠性功能、断路器模式、指标和批量操作，适用于商业部署和大规模部署。

📜 许可证概览

个人、教育和非营利用途免费。 任何商业、SaaS、创收或多租户部署都需要付费商业许可证。

商业许可咨询：[email protected] 完整条款：LICENSE · 下方的许可证部分

功能

涵盖邮件／文件夹／账户／类别／评分／订阅／dns-firewall／usercheck／staging／缓存／诊断的 100 多个 MCP 工具——我们使用的每项 IMAP4rev2（RFC 9051）操作均已开放。请参阅 docs/TOOL_CATALOG.md 中按类别整理的完整列表及准确数量（每次构建时根据清单生成），或运行 imap_list_tools 查看运行时的实时目录。

核心功能

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

本地邮件缓存 + 自动安装的技能（v2.17.0+）

• 本地 SQLite 标头缓存，用于快速枚举发件人。imap_sync_folder_cache 会为每个文件夹填充缓存；imap_search_cache 可在毫秒内对缓存运行 group_by_sender / by_domain / by_address 查询。已针对包含 1500 封邮件的 INBOX 完成端到端验证：冷同步耗时 1.7 秒，热缓存按发件人分组耗时 4 毫秒。
• 感知 UIDVALIDITY 的增量同步：后续同步只获取新的 UID。系统会自动检测邮箱重新编号并触发完整重新同步。
• 缓存未命中会明确提示：如果某个文件夹尚未同步，imap_search_cache 会返回结构化的 cache_miss 错误，不会静默回退到 IMAP。技能会负责协调执行顺序。
• 自动安装技能：随附的 Claude 技能（v2.17.0 中的 unsubscribe-cleanup）会在服务启动时复制到 ~/.claude/skills/imap-mcp-pro/。此操作具有幂等性：版本相同时跳过，捆绑版本较新时更新；如果磁盘上的内容版本更高，则予以保留。可通过 IMAP_MCP_SKIP_SKILLS_INSTALL=1 禁用。
• 从公共 GitHub 更新技能（v2.17.4+）：新增两个工具 imap_check_skill_updates 和 imap_update_skills，无需重新安装 .mcpb 即可从此仓库获取较新的技能版本。无需 PAT——默认来源为 MCP 自身的公共仓库。完整指南（含信任模型）请参阅 docs/SKILLS.md。

v2.0 可靠性与附件（v2.15.0+）

• 自动归档到已发送文件夹：imap_send_email 会根据服务提供商（Gmail / Outlook / iCloud / Fastmail / Yahoo / Hostinger / Zoho / GMX / ProtonMail）将每封邮件归档到正确的“已发送”文件夹。根据 RFC 5322 §3.6.3，归档副本会保留密送（Bcc）信息。失败的操作会进入后台队列重试，不会丢失。
• 带分类重试的 SMTP 连接池：使用 nodemailer 连接池，对暂时性故障采用指数退避；认证失败则立即报告（不重试），并提供针对服务提供商的指导（例如：“Gmail 要求使用应用专用密码，请在此处生成……”）。
• 基于路径的附件（attachmentPaths）：传入绝对文件路径，而非 Base64。服务会根据允许目录白名单进行验证（支持按用户覆盖），检查 realpath 和符号链接目标，限制文件大小，并根据 RFC 2183 清理文件名。
• 分块上传附件：适用于无法访问服务端文件系统的客户端。4 个工具组成的工作流（stage_init → stage_append × N → stage_finalize → imap_send_email stagedAttachmentIds=[...]）。分块顺序不影响重组；重复的 chunkIndex 具有幂等性；最终处理时会验证 SHA-256。
• 诊断工具：imap_test_smtp、imap_test_sent_folder、imap_get_smtp_metrics、imap_list_unarchived_sends、imap_list_staged_attachments。

企业版功能（Pro 版）

第 1 级：增强连接能力

• ⚡ 增强型保活：符合 RFC 2177，按每 29 分钟发送一次 NOOP 命令
• 🔌 连接监控：实时跟踪连接健康状况
• ✅ 连接验证：主动验证连接状态

第 2 级：高级可靠性

• 🔄 自动重连：指数退避（1s → 2s → 4s → 8s → 最长 60s）
• ♻️ 重试逻辑：为所有操作提供透明重试包装（最多 5 次尝试）
• 🏥 健康检查：每 29 分钟定期发送 NOOP，防止超时
• 📊 连接状态机：DISCONNECTED → CONNECTING → CONNECTED → RECONNECTING → ERROR
• ⚡ 批量操作：高效执行批量删除、读取和标记操作

第 3 级：生产级弹性能力

• 🛡️ 熔断器：防止故障级联（5 次失败后开启，2 次成功后关闭）
• 📦 操作队列：在服务中断期间将操作加入队列，重新连接后重放（最多 1000 项）
• 📈 全面的指标：按连接和操作统计指标（操作数、成功率、延迟、运行时间百分比）
• 🎯 优雅降级：只读模式、结果缓存（TTL 为 5 分钟）、回退到最近一次已知的正常数据
• 🔍 增强监控：通过 MCP 工具实时查看指标（imap_get_metrics、imap_get_operation_metrics）

多租户 / MSP 部署

🏢 面向 MSP 的商业许可证

IMAP MCP Pro 支持托管服务提供商（MSP）使用商业许可证配置多用户：

• 👥 用户隔离：客户之间实现完全的数据隔离
• 🔐 按客户分别认证：为每个租户配置独立凭据
• 🛡️ 基于角色的访问控制：设置管理员和用户角色，并进行细粒度权限管理
• 📊 使用情况跟踪：按客户统计 API 使用情况和指标
• 🎛️ 集中管理：通过单次安装管理多个客户部署

配置：

{
  "mcpServers": {
    "imap-customer-a": {
      "env": {
        "MCP_USER_ID": "customer-a"
      }
    },
    "imap-customer-b": {
      "env": {
        "MCP_USER_ID": "customer-b"
      }
    }
  }
}

商业授权咨询：

• 电子邮件：[email protected]
• MSP / 多租户部署需要商业许可证
• 根据 PolyForm Noncommercial License 1.0.0，非商业用途可免费使用

安装

Claude Desktop 扩展（.mcpb）——推荐最终用户使用

最快的配置方式是将 IMAP MCP Pro 安装为 Claude Desktop 扩展（.mcpb）。它将所有内容（Node 运行时、依赖项、原生模块）打包到一个归档文件中，并在 Claude Desktop 中显示原生设置面板——无需使用终端，也无需编辑 JSON。

1. 从 Releases 页面下载适用于你平台的最新 .mcpb（例如 imap-mcp-pro-2.14.0-macos-arm64.mcpb）。
2. 在 Claude Desktop 中，打开 Settings → Extensions → Install Extension…，然后选择下载的文件。
3. 填写出现的设置面板：
   • Data Directory — 数据库和缓存的存储位置（默认：~/.imap-mcp-pro）
   • Log Level — 日常使用选择 INFO 即可；排查问题时选择 DEBUG
   • Maximum Attachment Size — 默认值为 25 MiB
   • Allowed Attachment Directories — 可选，仅在通过路径发送附件时需要
   • Encryption Key — 留空可自动生成基于文件的密钥（存储于 ~/.imap-mcp/.encryption-key，模式为 600）；凭据使用 AES-256-GCM 加密（推荐）
   • User ID — 单用户安装时使用 default
4. 点击 Enable。向 Claude 提问 What IMAP accounts do I have?，快速测试是否正常。

安装后，要添加账户，请让 Claude 使用 imap_add_account_auto（自动检测提供商），或使用 Web UI：在命令行运行 imap-setup。

要升级，请下载较新的 .mcpb 并重新安装——你的数据目录会保留。

macOS — 安装包（推荐）

从 Releases 页面下载最新的 .dmg：

1. 打开 IMAP-MCP-Pro-x.x.x.dmg
2. 双击其中的 .pkg
3. 按照安装程序的提示操作，它将：
   • 提示设置 Web UI 端口（默认：4500）
   • 提议自动配置 Claude Desktop（如果已安装）
   • 安装 ImapMCPControl 菜单栏应用
   • 注册并启动后台服务

安装后，菜单栏中会出现信封图标。可随时使用 Preferences…（⌘,）更改设置。

安装内容：

路径	内容
~/.local/share/imap-mcp-pro/	服务端文件、捆绑的 Node.js 运行时
~/Applications/ImapMCPControl.app	菜单栏状态/控制应用
~/Library/LaunchAgents/com.templeofepiphany.imap-mcp-pro.plist	后台服务定义
~/.imap-mcp/	数据库和加密密钥（首次运行时创建）

macOS — 升级

在现有安装上运行相同的 .pkg 安装程序。安装程序会检测之前的版本，并且：

• 保留端口设置和 Claude Desktop 配置
• 停止服务，替换服务端文件，然后自动重启
• 不会触碰 ~/.imap-mcp/（你的账户和数据）

Linux / 手动安装

1. 克隆仓库：

git clone https://github.com/Temple-of-Epiphany/imap-mcp-pro.git
cd imap-mcp-pro

2. 安装依赖项并构建：

npm install
npm run build

3. 安装并启动服务：

make install

账户设置

网页设置向导（推荐）

安装后，运行设置向导：

npm run setup

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

imap-setup

向导将：

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

支持的电子邮件提供商

设置向导包含以下提供商的预配置设置：

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

配置

Claude Desktop 配置

macOS pkg 安装程序： Claude Desktop 会在安装过程中自动完成配置。你也可以通过菜单栏应用中的 Preferences… → Claude Desktop Integration 管理配置。

手动配置 — 编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "imap-mcp-pro": {
      "command": "/Users/YOUR_USERNAME/.local/share/imap-mcp-pro/runtime/node/bin/node",
      "args": ["/Users/YOUR_USERNAME/.local/share/imap-mcp-pro/dist/index.js"],
      "env": {
        "MCP_USER_ID": "YOUR_USERNAME"
      }
    }
  }
}

更改任何配置后，请重启 Claude Desktop。

环境变量

以下环境变量可在 Claude Desktop 配置中设置：

变量	描述	默认值	必填
MCP_USER_ID	多租户部署的用户标识符。按用户隔离账户和数据。	default	否
PORT	Web UI 服务的端口号	4500	否
NODE_ENV	Node 环境模式。设置为 development 可显示详细的错误堆栈跟踪。	production	否
IMAP_MCP_VERSION	版本标识符（由安装程序自动设置）	（软件包版本）	否
IMAP_MCP_TOOL_PROFILE	服务公开哪些工具：full（全部工具）或 core（约 29 个日常常用工具，适用于无法处理大量工具的宿主）。在 Claude Desktop 扩展中，此项为 Tool Profile 选项。请参阅 工具配置文件。	full	否

工具配置文件

该服务注册了约 130 个 MCP 工具。有些宿主会公布全部工具，但不会在会话中显示任何工具（在 Claude Desktop Cowork bridge 中观察到，#293）。设置扩展选项 Tool Profile（或 IMAP_MCP_TOOL_PROFILE）来选择公开的工具数量：

配置文件	注册的工具
full（默认）	全部工具。
core	日常常用工具（约 29 个）：列出用户/账户并测试账户；搜索、读取、获取最新邮件、未读邮件计数、附件；发送、回复、转发、发件箱目录；列出文件夹及文件夹状态；标记为已读/未读、移动、复制、删除（单个和批量）；以及 imap_list_tools、imap_help、imap_about、imap_open_web_ui。

imap_list_tools 始终会报告当前使用的配置文件以及隐藏工具的名称。未知值会回退到 full，并在服务日志中发出警告。更改选项后，请重启 Claude Desktop。无论使用哪个配置文件，.mcpb 清单始终会列出完整目录。

多用户配置示例：

{
  "mcpServers": {
    "imap-work": {
      "command": "node",
      "args": ["/path/to/imap-mcp-pro/dist/index.js"],
      "env": {
        "MCP_USER_ID": "work",
        "PORT": "4500"
      }
    },
    "imap-personal": {
      "command": "node",
      "args": ["/path/to/imap-mcp-pro/dist/index.js"],
      "env": {
        "MCP_USER_ID": "personal",
        "PORT": "3001"
      }
    }
  }
}

注意： 每个 MCP_USER_ID 都会创建独立的：

• 账户存储（数据库）
• CleanTalk API 密钥配置
• Web UI 实例（使用指定的 PORT）
• 会话数据和凭据

用法

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

账户管理

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

• 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)
  - from, to, subject, body: Search criteria
  - since, before: Date filters
  - seen, flagged: Status filters
  - limit: Max results (default: 50)
  

• imap_get_email：获取完整邮件内容

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

• imap_get_latest_emails：获取近期邮件

  Parameters:
  - accountId: Account ID
  - folder: Folder name (default: INBOX)
  - count: Number of emails (default: 10)
  

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

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

• imap_delete_email：删除邮件

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

• imap_send_email：发送新邮件

  Parameters:
  - accountId: Account ID to send from
  - to: Recipient email address(es)
  - 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
    - path: File path to attach
    - contentType: MIME type
  

• 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)
  - attachments: Array of attachments (optional)
  

• 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)
  - includeAttachments: Include original attachments (default: true)
  

• imap_copy_email：将邮件复制到另一个文件夹

  Parameters:
  - accountId: Account ID
  - sourceFolder: Source folder name (default: INBOX)
  - uid: Email UID to copy
  - targetFolder: Target folder name
  

• imap_bulk_copy_emails：将多封邮件批量复制到另一个文件夹

  Parameters:
  - accountId: Account ID
  - sourceFolder: Source folder name (default: INBOX)
  - uids: Array of email UIDs to copy
  - targetFolder: Target folder name
  

• imap_move_email：将邮件移动到另一个文件夹

  Parameters:
  - accountId: Account ID
  - sourceFolder: Source folder name (default: INBOX)
  - uid: Email UID to move
  - targetFolder: Target folder name
  

• imap_bulk_move_emails：将多封邮件批量移动到另一个文件夹

  Parameters:
  - accountId: Account ID
  - sourceFolder: Source folder name (default: INBOX)
  - uids: Array of email UIDs to move
  - targetFolder: Target folder name
  

自动分块（智能批量操作）

所有批量操作现在都会自动对 >50 个 UID 的操作进行分块！ 无需在常规工具和分块工具之间做选择，系统会智能地为你处理。

工作原理：

• ≤50 个 UID：快速单批处理
• >50 个 UID：自动分块处理（每块 100 个 UID）
• 进度跟踪：在服务日志中实时记录
• 错误恢复：即使个别分块失败，也会继续处理

分块批量操作（大规模处理）

如需明确控制分块行为：

• imap_bulk_mark_emails_chunked：针对大规模操作，分块标记邮件

  Parameters:
  - accountId: Account ID
  - folder: Folder name (default: INBOX)
  - uids: Array of email UIDs to mark (supports 1000+ UIDs)
  - operation: Mark operation (read, unread, flagged, unflagged, answered, unanswered, draft, not-draft, deleted, undeleted)
  - chunkSize: Number of emails per chunk (default: 100)
  
  Returns:
  - processed: Number of successfully processed emails
  - failed: Number of failed emails
  - errors: Array of error details for failed chunks
  

• imap_bulk_delete_emails_chunked：针对大规模操作，分块删除邮件

  Parameters:
  - accountId: Account ID
  - folder: Folder name (default: INBOX)
  - uids: Array of email UIDs to delete (supports 1000+ UIDs)
  - expunge: Permanently expunge deleted emails (default: false)
  - chunkSize: Number of emails per chunk (default: 100)
  
  Returns:
  - processed: Number of successfully deleted emails
  - failed: Number of failed emails
  - errors: Array of error details for failed chunks
  

• imap_bulk_get_emails_chunked：针对大规模操作，分块获取邮件

  Parameters:
  - accountId: Account ID
  - folder: Folder name (default: INBOX)
  - uids: Array of email UIDs to fetch (supports 1000+ UIDs)
  - fields: Fields to fetch (headers, body, or full)
  - chunkSize: Number of emails per chunk (default: 100)
  
  Returns:
  - count: Number of successfully fetched emails
  - totalRequested: Total number of UIDs requested
  - emails: Array of fetched email objects
  

用例示例： 处理 1700 封未读邮件，标记批量营销邮件以便删除：

1. 搜索未读邮件：使用 imap_search_emails，并设置 seen: false
2. 分块获取邮件头：使用 imap_bulk_get_emails_chunked，传入 1700 个 UID 和 chunkSize: 100
3. 在应用逻辑中筛选营销邮件
4. 分块删除：使用 imap_bulk_delete_emails_chunked，并传入筛选后的 UID

优势：

• 通过分批处理，避免触发熔断器
• 即使个别分块失败，也会继续处理
• 提供进度跟踪和错误报告
• 分块之间延迟 100ms，避免服务过载

文件夹操作

• imap_list_folders：列出所有文件夹

  Parameters:
  - accountId: Account ID
  

• imap_folder_status：获取文件夹信息

  Parameters:
  - accountId: Account ID
  - folder: Folder name
  

• imap_get_unread_count：统计未读邮件数量

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

卸载

macOS

使用菜单栏应用，或在项目目录中运行：

# Interactive uninstall (prompts before removing data)
make uninstall

# Or run the script directly
distributions/osx/scripts/uninstall.sh

卸载程序会：

• 停止并移除 LaunchAgent
• 移除 ~/Applications/ImapMCPControl.app
• 移除 ~/.local/share/imap-mcp-pro/
• 清除 pkgutil 收据
• 移除 ~/.imap-mcp/（你的账户和数据）前会提示确认
• 移除 Claude Desktop MCP 条目前会提示确认

Linux

make uninstall

---

备份与恢复

你的数据存储在 ~/.imap-mcp/ 中，包括：

文件	内容
data.db	SQLite 数据库 — 所有账户、设置和历史记录
.encryption-key	用于加密已存储密码的 AES-256 密钥
.key	次级密钥文件

**重要：**没有密钥文件的备份无法解密已存储的密码。请务必一起备份整个 ~/.imap-mcp/ 目录。

**WAL 模式（v2.34.0+）：**数据库使用 SQLite WAL 日志模式，以便多个服务共享该数据库（Claude Desktop 会为每个主机运行一个服务）。最近的写入可能会在检查点完成前保留在 data.db-wal 中，因此请勿使用 cp 复制 data.db 来备份。请使用下方的备份功能，或运行 sqlite3 ~/.imap-mcp/data.db ".backup '/path/to/copy.db'"。

备份

菜单栏应用：“Preferences…” → “Database” → “Backup”
保存一个包含数据库和两个密钥文件的 .zip 文件。

命令行：

# Save to ~/imap-mcp-pro-backup-YYYY-MM-DD.zip
make backup

# Save to a specific path
scripts/backup.sh /path/to/backup.zip

该脚本使用 sqlite3 .backup 创建一致性快照（服务运行时也安全），因此必须安装 sqlite3 命令行工具。

恢复

菜单栏应用：“Preferences…” → “Database” → “Restore”
选择一个 .zip 备份 — 服务会停止、替换数据，然后重新启动。

命令行：

make restore FILE=/path/to/backup.zip

# Or directly
scripts/restore.sh /path/to/backup.zip

恢复脚本会在替换文件前停止服务，并在完成后自动重新启动。

---

安全性

• 凭据使用 AES-256-GCM 加密
• 加密密钥单独存储在 ~/.imap-mcp/ 中
• 数据库存储在 ~/.imap-mcp/data.db
• 切勿提交或分享你的加密密钥或数据库

隐私政策

IMAP MCP Pro 完全在你的设备上运行，不会向发布者发送任何数据——没有遥测，也没有由我们运营的服务器。它只处理你配置的电子邮件账户；凭据在静态存储时经过加密（AES-256-GCM），所有本地文件仅所有者可访问。只有在你主动操作时，数据才会离开你的设备：发送到你自己的 IMAP/SMTP 服务器、你启用的可选集成（用于垃圾邮件检查的 UserCheck、用于防火墙检查的 DNS-over-HTTPS 提供商），以及你使用的 Claude 客户端。数据只会在本地保留，直到你将其删除（移除账户、清除缓存或删除 ~/.imap-mcp/）。

完整政策——涵盖收集的数据、存储、与第三方共享、保留期限和联系方式：PRIVACY.md。

开发

在开发模式下运行

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
│   └── database-service.ts # Encrypted account/user storage (SQLite)
├── 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. 管理文件夹： “列出我邮箱账户中的所有文件夹，并显示未读邮件数量”

故障排除

连接问题

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

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
  • 需要专用应用密码

故障排除

日志存放在哪里？

Claude Desktop 会将服务器的标准错误输出保存到每个服务器各自的日志文件中：

平台	路径
macOS	~/Library/Logs/Claude/mcp-server-imap-mcp-pro.log
Windows	%APPDATA%\Claude\logs\mcp-server-imap-mcp-pro.log
Linux	~/.local/state/Claude/logs/mcp-server-imap-mcp-pro.log

查找类似 [startup] stage=pre-handshake outcome=ok duration_ms=12 的行，以确认服务器已正常启动。如果预握手耗时超过 2 s，你会看到一行 outcome=warning。

常见故障

“配置有效”，但工具在运行时失败 运行 node /path/to/server/dist/index.js --validate-config（或通过 .mcpb 扩展附带的服务运行）。它会打印每个解析后的值，并将文件系统权限问题与架构错误分别标出。

启动时出现数据库错误（退出码 2） 通常是数据目录的权限问题。检查 --validate-config 输出中的 database.path——其父目录必须可写。

工具首次调用时返回“正在预热”响应 后台服务仍在初始化（握手后阶段）。等待几秒钟后重试。如果问题仍然存在，请检查日志中是否有 outcome=error 行。

服务在 Claude Desktop 中似乎没有响应 通常是握手前超时。先用 --validate-config 确认；如果检查无误，请查看日志中的握手前 duration_ms——超过 2000 就会超时。

配置未读取环境变量 运行 --validate-config，查看字段旁边的 [source] 标签。来源按优先级从高到低排列：cli > env > file > default。如果你预期看到 [env]，却显示 [default]，环境变量名称可能有误——请参阅 src/config/server-config.ts:ENV_VAR_MAPPING 中的规范映射。

检查配置架构

node dist/index.js --print-config-schema | jq .

返回 ServerConfig 的完整 JSON Schema，包含每个字段的类型、默认值、描述和验证范围。

检查工具目录

node dist/index.js --print-tools-manifest | jq '.tools | length'

文档

• EXAMPLES.md — 常见工作流的 Claude 对话记录示例
• docs/SKILLS.md — 捆绑技能、自动安装行为、GitHub 更新工具和贡献者指南
• docs/ARCHITECTURE.md — 代码库概览、启动阶段、响应结构策略和贡献者指南
• docs/sdk_audit_2026-04-29.md — MCP SDK 对齐审计
• rfc/rfc9051.txt 中的 RFC 9051（IMAP4rev2）全文

许可证

个人使用免费，商业使用收费。

本软件采用双重许可模式分发：非商业用途适用 PolyForm Noncommercial License 1.0.0，其他用途则需要单独的商业许可证。你适用的许可证完全取决于你如何使用本软件。

✅ 非商业用途 — 免费（PolyForm Noncommercial License 1.0.0）

如果你的用途属于 PolyForm Noncommercial License 许可的非商业用途，即可免费使用、复制、修改和分发本软件，包括：

• 管理自己的个人电子邮件账户
• 教育用途（学生、教师、课堂）
• 学术研究项目
• 符合条件的非营利组织的内部运营
• 开源项目开发
• 评估、测试和概念验证工作

你可以为任何许可的非商业用途进行修改并创作新作品。（PolyForm Noncommercial 不要求相同方式共享或遵循 Copyleft。）

💼 商业许可证 — 收费（必须取得）

在将本软件用于以下任何用途之前，必须取得付费商业许可证：

• 营利性公司的商务电子邮件运营
• 任何 SaaS 产品、托管服务或付费服务
• 多租户或 MSP（托管服务提供商）部署
• 创收服务的生产环境部署
• 将本软件重新分发为商业产品的一部分
• 任何创收组织使用本软件（符合条件的非营利组织内部运营除外）

如果你的用途不在上述免费用途范围内，就需要商业许可证——即使你没有直接向用户收取电子邮件功能的费用。

获取商业许可证

联系： [email protected] 组织： Temple of Epiphany

商业许可证条款包括支持与维护、优先修复 Bug、生产环境部署权以及法律赔偿保障。提供永久许可和订阅两种方案。

不确定哪种情况适用于你？

如果你的使用场景无法明确归入非商业用途列表，请默认认为你需要商业许可证，并给我们发送邮件——我们很乐意为你解答。

完整法律条款：LICENSE。

致谢

本项目是由 Michael Nikolaus 创建的原始 IMAP MCP Server 的企业增强分支。

原始项目： https://github.com/nikolausm/imap-mcp-server 原作者： Michael Nikolaus 原始许可证： MIT License（仅适用于基础代码）

Temple of Epiphany 添加了大量企业级功能（级别 1–3），这些功能受上述双许可证模式约束。

贡献

欢迎贡献！对于商业用途的贡献，贡献者同意其贡献受本项目的双许可证模式约束。

欢迎提交 Pull Request，内容包括：

• Bug 修复
• 文档改进
• 新功能
• 性能增强

对于重大更改，请先创建 issue，讨论你希望进行的更改。