Email (IMAP/SMTP)

@mindstone/mcp-server-email-imap

面向 Model Context Protocol 主机的电子邮件 IMAP/SMTP MCP 服务。通过 IMAP 和 SMTP 阅读、搜索、发送和管理电子邮件 — 支持 iCloud Mail、Gmail、Yahoo Mail、Outlook / Microsoft 365 以及自定义 IMAP 服务提供商。

状态

• 版本： 0.3.2 · npm
• 身份验证： 应用专用密码 (EMAIL_IMAP_PASSWORD)
• 工具： 17（邮箱、邮件、草稿、发送）
• 接口： 本地协议
• 机器可读： STATUS.json

要求

• Node.js 20+
• npm

一键安装

点击按钮后，主机将提示你填写：EMAIL_IMAP_EMAIL、EMAIL_IMAP_PASSWORD、EMAIL_IMAP_IMAP_PORT、EMAIL_IMAP_SMTP_PORT、EMAIL_IMAP_MAX_RECIPIENTS、EMAIL_IMAP_RATE_LIMIT_PER_HOUR、EMAIL_IMAP_RATE_LIMIT_WINDOW_MS。

{
  "mcpServers": {
    "Email (IMAP/SMTP)": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-email-imap"
      ],
      "env": {
        "EMAIL_IMAP_EMAIL": "",
        "EMAIL_IMAP_PASSWORD": "",
        "EMAIL_IMAP_IMAP_PORT": "993",
        "EMAIL_IMAP_SMTP_PORT": "587",
        "EMAIL_IMAP_MAX_RECIPIENTS": "25",
        "EMAIL_IMAP_RATE_LIMIT_PER_HOUR": "50",
        "EMAIL_IMAP_RATE_LIMIT_WINDOW_MS": "3600000"
      }
    }
  }
}

快速开始

安装与构建

cd <path-to-repo>/connectors/email-imap
npm install
npm run build

npx（发布后）

npx -y @mindstone/mcp-server-email-imap

本地运行

node dist/index.js

配置

环境变量

• EMAIL_IMAP_EMAIL — 电子邮件地址
• EMAIL_IMAP_PASSWORD — 应用专用密码
• EMAIL_IMAP_PROVIDER — 电子邮件服务提供商（icloud、gmail、yahoo、outlook 或 custom）。未设置时，连接器会根据电子邮件域名自动检测服务提供商（例如，@gmail.com → gmail、@icloud.com → icloud、@outlook.com → outlook、@yahoo.co.uk → yahoo）。如果域名无法识别，连接器会拒绝启动并给出明确错误，不会悄悄回退到默认服务提供商。
• EMAIL_IMAP_IMAP_HOST — 自定义 IMAP 主机（可选，适用于 custom 服务提供商）
• EMAIL_IMAP_SMTP_HOST — 自定义 SMTP 主机（可选，适用于 custom 服务提供商）
• EMAIL_IMAP_IMAP_PORT — 自定义 IMAP 端口（默认：993）。配置后允许使用明文端口（imap_port=143、smtp_port=25）——是否使用明文由你的主机决定。
• EMAIL_IMAP_SMTP_PORT — 自定义 SMTP 端口（默认：587）
• MCP_WORKSPACE_PATH — 用于附件文件 I/O 的工作区目录。email_get_attachment 会将文件下载到直接创建在此路径下的全新私有暂存目录 email-imap-attachment-* 中（返回的 path 指向该目录）；email_send / email_save_draft / email_update_draft 的外发附件只能从该目录中读取（拒绝读取目录之外的路径，包括通过符号链接访问的路径）。成功下载的文件会保留其暂存目录（该目录包含返回的文件）；不再需要其中的文件后，可以安全删除累积的 email-imap-attachment-* 目录。未设置时，默认使用系统临时目录。
• MCP_HOST_BRIDGE_STATE — 可选的主机桥接状态文件路径，用于凭据管理
• MINDSTONE_REBEL_BRIDGE_STATE — 与 MCP_HOST_BRIDGE_STATE 向后兼容的别名

发送端限制（email_send）

这些限制充当熔断机制，限制由提示词注入驱动的大规模发送所造成的影响范围。默认值已写入源代码，因此即使主机未设置这些变量，也能确保安全行为。主机可以根据具体部署进一步收紧限制。

• EMAIL_IMAP_MAX_RECIPIENTS — 每次 email_send 调用中收件人、抄送和密送人数的总上限（默认：25）。超过此限制时，会返回包含 code: "RECIPIENT_LIMIT_EXCEEDED" 的结构化错误。
• EMAIL_IMAP_RATE_LIMIT_PER_HOUR — 每个滚动时间窗口内允许调用 email_send 的最大次数（默认：50）。超过此限制时，会返回包含 code: "RATE_LIMIT_EXCEEDED" 的结构化错误，以及 resetAt（ISO-8601）和 retryAfterMs，以便主机/大模型进行退避。
• EMAIL_IMAP_RATE_LIMIT_WINDOW_MS — 速率限制的滑动窗口时长，单位为毫秒（默认：3600000，即一小时）。

主机配置示例

Claude Desktop / Cursor

{
  "mcpServers": {
    "Email": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-email-imap"],
      "env": {
        "EMAIL_IMAP_EMAIL": "[email protected]",
        "EMAIL_IMAP_PASSWORD": "your-app-specific-password",
        "EMAIL_IMAP_PROVIDER": "icloud"
      }
    }
  }
}

本地开发（无需发布到 npm）

{
  "mcpServers": {
    "Email": {
      "command": "node",
      "args": ["<path-to-repo>/connectors/email-imap/dist/index.js"],
      "env": {
        "EMAIL_IMAP_EMAIL": "[email protected]",
        "EMAIL_IMAP_PASSWORD": "your-app-specific-password",
        "EMAIL_IMAP_PROVIDER": "icloud"
      }
    }
  }
}

安全性：email_send 需要主机确认

email_send 是一项破坏性、开放世界操作：它会代表用户向任意外部收件人发送邮件。因此，该工具被标注为 destructiveHint: true 和 openWorldHint: true。

主机必须在每次调用 email_send 前要求用户明确确认。 用户确认门槛是防止提示词注入内容（例如 email_get_message 正文中的文本）诱使大模型违背用户意愿发送邮件的唯一可靠防线。不要仅依据工具注释自动批准 email_send——应向用户显示完整的收件人列表、主题和正文，并要求用户明确点击或按键确认，然后再将调用转发给连接器。

连接器还会实施以下限制：

• To、CC 和 BCC 收件人的总数上限（EMAIL_IMAP_MAX_RECIPIENTS，默认为 25）。
• 每个进程的滚动速率限制 （EMAIL_IMAP_RATE_LIMIT_PER_HOUR / EMAIL_IMAP_RATE_LIMIT_WINDOW_MS， 默认为 50 / 3600000ms）。

超出任一上限时，工具会返回结构化错误 JSON （{ ok: false, code: "RECIPIENT_LIMIT_EXCEEDED" | "RATE_LIMIT_EXCEEDED", … }）， 且不会联系 SMTP 传输层。上限可通过环境变量调整，但默认值已写入源代码——主机无需设置任何环境变量即可获得安全行为。

安全性：不可信内容封装与破坏性工具

连接器返回的所有由攻击者控制的文本字段——邮件正文、主题、发件人／收件人显示名称、Message-ID、附件文件名、MIME 内容类型和部分标识符、邮箱名称和特殊用途值、邮件标志关键字（通过 email_set_flags 写入；关键字必须符合严格的字符集允许列表——字母、数字、_、$、.、-，并可选择以 \ 开头，因此空格、括号、引号或 CR/LF 等 atom 特殊字符绝不会进入 IMAP 命令）、草稿摘要，以及源自 IMAP／SMTP 服务器或供应商 SDK 的错误文本——都会被包裹在 <untrusted-content …>…</untrusted-content> 封装中（并对闭合标签逸出进行处理），使主机大模型将其视为数据而非指令。使用先前返回值的工具（mailbox、part、邮箱名称、标志关键字）会原样接受已封装的形式，并在输入时剥除一层封装。

除 email_send 外，带有 destructiveHint: true 标注的工具还包括：email_save_draft、email_update_draft（替换并彻底删除旧草稿）、email_create_mailbox、email_rename_mailbox、email_delete（不存在 Trash 邮箱时会永久删除；移动到 Trash 失败时会中止并返回 TRASH_MOVE_FAILED 错误——邮件会保留原位，而不会悄然升级为永久删除）、email_move_messages（其回退操作会永久删除源邮件，且仅在确认每个 UID 均已成功复制到目标位置后执行——否则会中止并返回 MOVE_COPY_UNVERIFIED 错误）、email_set_flags（\Deleted 会将邮件标记为在邮箱关闭时永久删除）、email_delete_draft（始终永久删除）以及 email_delete_mailbox（删除文件夹及其中的所有邮件）。主机应像对待 email_send 一样，在调用这些工具前要求用户明确确认。

工具（17）

配置

• configure_email_imap — 配置电子邮件账户凭据和服务提供商

邮箱

• email_list_mailboxes — 列出所有电子邮件文件夹／邮箱及邮件数量
• email_get_mailbox_status — 获取邮箱状态，包括未读邮件数量和最新主题
• email_create_mailbox — 创建新的邮箱／文件夹（具有破坏性）
• email_rename_mailbox — 重命名邮箱／文件夹（不能重命名 INBOX；具有破坏性）
• email_delete_mailbox — 永久删除邮箱／文件夹及其内容（具有破坏性）

消息

• email_search_messages — 根据发件人、主题、未读状态筛选邮件，支持 since/before 日期筛选和 before_uid 游标分页（未指定 limit 时最多返回 50 封邮件；hasMore: true 表示还有更多结果）
• email_get_message — 根据 UID 获取完整邮件内容（正文、主题、地址、Message-ID 以及附件文件名和 MIME 元数据会封装在 <untrusted-content> 中返回）
• email_get_attachment — 将附件下载到工作区沙盒（参见 MCP_WORKSPACE_PATH）；采用独占创建方式写入，因此不会覆盖现有文件
• email_move_messages — 在文件夹之间移动邮件（仅在确认复制完整后，才会回退并清除源文件夹中的邮件；具有破坏性）
• email_delete — 删除邮件（如果存在 Trash，则将邮件移至 Trash，否则永久清除；如果移至 Trash 失败，则中止并报错；具有破坏性）
• email_set_flags — 为邮件设置或移除标记（已读、星标）（标记关键词会以封装形式返回，输入时必须符合字符集允许列表；具有破坏性）

草稿

• email_save_draft — 保存邮件草稿（支持附件；会修改远程账户，具有破坏性）
• email_list_drafts — 列出 Drafts 邮箱中的草稿（每次调用最多 50 封；hasMore: true 表示还有更多草稿）
• email_update_draft — 替换草稿内容（先保存新版本，再移除旧版本；具有破坏性）
• email_delete_draft — 永久删除草稿（具有破坏性）

发送

• email_send — 发送邮件或回复（支持附件）

许可证

FSL-1.1-MIT — Functional Source License 1.1 版，并将在未来采用 MIT 许可证。该软件将于 2030-04-08 转为 MIT 许可证。