MCP Mail Server

语言： English | 中文

一个用于 IMAP/SMTP 邮件操作的 Model Context Protocol 服务器，可与 Claude、Cursor 及其他 AI 助手配合使用。

功能特性

• IMAP 操作：跨邮箱搜索、读取和管理邮件

• SMTP 支持：发送包含 HTML/文本内容和附件的邮件

• 附件管理：查看附件元数据并保存附件到本地文件

• 安全配置：基于环境变量的配置方式，支持 TLS/SSL

• AI 友好：通过自然语言命令完成邮件操作

• 自动连接管理：自动处理 IMAP/SMTP 连接

• 多邮箱支持：访问 INBOX、Sent 及自定义文件夹

更新日志

[1.2.1] - 2026-03-18

修复

• 修复搜索条件（FROM/TO/SUBJECT/BODY/KEYWORD/SINCE）未使用嵌套数组格式，导致 TO 等搜索出错的问题

• 修复 search() 多包一层数组，导致复合搜索条件失效的问题

• 修复 deleteMessage() 在邮箱以只读模式打开时静默失败的问题

• 修复 getRecentMessages() 误用 IMAP RECENT 标志；现在改为按 UID 获取最新 N 封邮件

• 修复 getRecentMessages() / getUnseenMessages() 依赖前一次操作遗留邮箱状态的问题

• 修复 cleanReplySubject() 只移除一层 Re: 前缀，导致未回复检测出现漏报的问题

• 修复邮件日期以 locale 字符串存储，导致不同平台上 new Date() 解析结果不一致的问题；已改为 ISO 8601

• 修复 ensureIMAPConnection() 在等待并发初始化时没有超时的问题

• 修复 saveSentMessage() 即使保存失败也始终返回 sentFolderSaved: true 的问题

• 修复 handleGetMessages() / handleDeleteMessage() 依赖 currentBox 状态定位邮件的问题

• 修复 reply_to_email 在 text 为空时向正文写入字面值 "undefined" 的问题

新增

• 所有搜索工具现在都支持 inboxOnly 参数，可将搜索范围限制为仅收件箱（INBOX）

改进

• ensureSMTPConnection() 现在增加了并发保护，并设置 30 秒超时，与 IMAP 一致

• 通过 RFC 6154 的 \Sent 特殊用途属性自动检测“已发送”邮箱，并缓存结果，兼容所有邮件服务商

• 简化 saveMessageToFolder()；如果找不到“已发送”文件夹，则跳过保存

• 搜索现在使用 slice(-limit) 优先获取最新邮件，避免日期过滤后结果为空

• 对回复邮件中的引用内容进行 HTML 转义，防止 XSS 注入

如需查看完整的版本历史，请参阅 CHANGELOG.md。

快速开始

1. 安装：执行 npm install -g mcp-mail-server

2. 配置环境变量（参见 配置）

3. 添加到您的 MCP 客户端配置中

4. 使用自然语言指令：“Show me unread emails from today”

安装

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["-y", "mcp-mail-server"],
      "env": {
        "IMAP_HOST": "your-imap-server.com",
        "IMAP_PORT": "993",
        "IMAP_SECURE": "true",
        "SMTP_HOST": "your-smtp-server.com",
        "SMTP_PORT": "465",
        "SMTP_SECURE": "true",
        "EMAIL_USER": "your-email@domain.com",
        "EMAIL_PASS": "your-password"
      }
    }
  }
}

在 Cursor 的 MCP 设置中添加：

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["-y", "mcp-mail-server"],
      "env": {
        "IMAP_HOST": "your-imap-server.com",
        "IMAP_PORT": "993",
        "IMAP_SECURE": "true",
        "SMTP_HOST": "your-smtp-server.com",
        "SMTP_PORT": "465",
        "SMTP_SECURE": "true",
        "EMAIL_USER": "your-email@domain.com",
        "EMAIL_PASS": "your-password"
      }
    }
  }
}

使用 claude mcp add 命令添加：

claude mcp add mcp-mail-server \
  -e IMAP_HOST=your-imap-server.com \
  -e IMAP_PORT=993 \
  -e IMAP_SECURE=true \
  -e SMTP_HOST=your-smtp-server.com \
  -e SMTP_PORT=465 \
  -e SMTP_SECURE=true \
  -e EMAIL_USER=your-email@domain.com \
  -e EMAIL_PASS=your-password \
  -- npx -y mcp-mail-server

或者手动添加到 .claude/settings.json：

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["-y", "mcp-mail-server"],
      "env": {
        "IMAP_HOST": "your-imap-server.com",
        "IMAP_PORT": "993",
        "IMAP_SECURE": "true",
        "SMTP_HOST": "your-smtp-server.com",
        "SMTP_PORT": "465",
        "SMTP_SECURE": "true",
        "EMAIL_USER": "your-email@domain.com",
        "EMAIL_PASS": "your-password"
      }
    }
  }
}

添加到项目根目录下的 codex.json：

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["-y", "mcp-mail-server"],
      "env": {
        "IMAP_HOST": "your-imap-server.com",
        "IMAP_PORT": "993",
        "IMAP_SECURE": "true",
        "SMTP_HOST": "your-smtp-server.com",
        "SMTP_PORT": "465",
        "SMTP_SECURE": "true",
        "EMAIL_USER": "your-email@domain.com",
        "EMAIL_PASS": "your-password"
      }
    }
  }
}

其他 MCP 客户端可以通过类似方式配置。核心配置如下：

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["-y", "mcp-mail-server"],
      "env": {
        "IMAP_HOST": "your-imap-server.com",
        "IMAP_PORT": "993",
        "IMAP_SECURE": "true",
        "SMTP_HOST": "your-smtp-server.com",
        "SMTP_PORT": "465",
        "SMTP_SECURE": "true",
        "EMAIL_USER": "your-email@domain.com",
        "EMAIL_PASS": "your-password"
      }
    }
  }
}

配置文件的存放位置请参阅对应客户端的文档。

可用工具

连接管理

• connect_all：无需参数

• get_connection_status：无需参数

• disconnect_all：无需参数

邮箱操作

• open_mailbox：mailboxName（字符串，默认值："INBOX"）、readOnly（布尔值）

• list_mailboxes：无需参数

搜索操作

• search_by_sender：sender（字符串，邮箱地址）、start（字符串，可选）、end （字符串，可选）

• search_by_subject：subject（字符串，关键字）、start（字符串，可选）、end（字符串，可选）

• search_by_recipient：recipient（字符串，邮箱地址）、start（字符串，可选）、end（字符串，可选）

• of body：text（字符串，搜索文本）、startDate（字符串，可选）、endDate（字符串，可选）

• search_since_date：date（字符串，日期格式）

• search_unread_from_sender：sender（字符串，邮箱地址）、startDate（字符串，可选）、endDate（字符串，可选）

• search_unreplied_from_sender：sender（字符串，邮箱地址）、startDate（字符串，可选）、endDate（字符串，可选）、limit（数字，可选）

• search_with_keyword：keyword（字符串，关键字）、startDate（字符串，可选）、endDate（字符串，可选）

• search_all_messages：startDate（字符串，可选）、endDate（字符串，可选）、limit（数字，可选，默认值：50）

邮件操作

• get_message_count：无需参数

• get_unseen_messages：无需参数

• get_recent_messages：无需参数

• get_message：uid（数字）、markSeen（布尔值，可选）

• get_messages：uids（数组）、markSeen（布尔值，可选）

• delete_message：uid（数字）

发送邮件

• send_email：to（字符串）、subject（字符串）、text（字符串，可选）、html（字符串，可选）、cc（字符串，可选）、bcc（字符串，可选）、attachings（字符串数组，可选，绝对路径）

• reply_to_email：originalUuid（数字）、text（字符串）、html（字符串，可选）、replyToAll（布尔值，可选）、includeOriginal（布尔值，可选）

附件操作

• 附件操作：uid（数字）— 返回元数据：文件名、contentType、size、index

• save_attachment：uid（数字）、savePath（字符串，绝对路径）、attachmentIndex（数字，可选，0 基索引）、returnBase64（布尔值，可选，默认值：false）

使用示例

通过自然语言命令使用辅助功能：

基本操作

• “连接我的邮件服务器”

• “显示所有未读邮件”

• “搜索来自 boss@company.com 的邮件”

• “给 team@company.com 发送一封关于会议的邮件”

• “回复 UID 为 123 的邮件”

高级搜索

• “查找上周主题中包含"紧急"的邮件”

• “显示来自 boss@company.com 的未回复邮件”

• “搜索发送给 team@company.com 的邮件”

• “获取 Sales 文件夹中的所有邮件”

• “显示来自 boss@company.com 的未读邮件”

• “显示过去 7 天的所有邮件”

• “列出所有邮件，限制为 20 封”

邮件管理

• “删除 UID 为 123 的邮件”

• “将最近的邮件标记为已读”

• “列出我所有的邮件文件夹”

附件操作

• “显示 UID 为 456 的邮件的附件”

• “将 UID 为 456 的邮件的所有附件保存到 D:/Downloads”

• “下载 UID 为 789 的邮件的第一个附件”

• “向 team@company.com 发送一封带有附件 D:/report.pdf 的邮件”

配置

环境变量

** 所有变量都是必需的**

可选变量

旧 Error mode (stdio/HTTP)

默认情况下，服务器通过 stdio 运行（这是本地客户端适用的标准 MCP 传输模式）。也可以作为 可流式 HTTP 服务器运行，并可选启用 HTTPS。

当找到证书和私钥时，服务器将通过 HTTPS 运行；否则，它将回退到明文 HTTP 并发出警告。

使用 mkcert 生成本地受信任的证书：

mkcert -install   # one-time: install the local CA
mkcert -cert-file certs/localhost-cert.pem -key-file certs/localhost-key.pem localhost 127.0.0.1 ::1

在 HTTP 模式下运行：

MCP_TRANSPORT=http MCP_HTTP_PORT=8443 npm start
# → MCP endpoint:  https://localhost:8443/mcp
# → Health check:  https://localhost:8443/health

MCP 端点位于 /mcp，根据 Streamable HTTP 规范支持会话管理（通过 mcp-session-id 头）和 SSE 流式传输。

常见邮件提供商

IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_SECURE=true
SMTP_HOST=smtp.gmail.com
SMTP_PORT=465
SMTP_SECURE=true
EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-app-password

注意：请使用应用专用密码，而不是您的常规密码。

IMAP_HOST=outlook.office365.com
IMAP_PORT=993
IMAP_SECURE=true
SMTP_HOST=smtp.office365.com
SMTP_PORT=587
SMTP_SECURE=true
EMAIL_USER=your-email@outlook.com
EMAIL_PASS=your-password

安全注意事项

• 使用应用专用密码：启用双重验证（2FA），并在可用时使用应用专用密码

• 需要 TLS/SSL：始终使用安全连接（IMAP_SECURE=true、SMTP_SECURE=true）

• 环境变量：切勿在配置文件中硬编码凭据

开发

1. 克隆仓库：

   git clone https://github.com/yunfeizhu/mcp-mail-server.git
   cd mcp-mail-server

2. 安装依赖：

   npm install

3. 构建项目：

   npm run build

4. 设置环境变量：

   export IMAP_HOST=your-imap-server.com
   export IMAP_PORT=993
   export IMAP_SECURE=true
   export SMTP_HOST=your-smtp-server.com
   export SMTP_PORT=465
   export SMTP_SECURE=true
   export EMAIL_USER=your-email@domain.com
   export EMAIL_PASS=your-password

5. 运行服务器：

   npm start

贡献

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

许可证

MIT License —— 详见 LICENSE 文件。

包信息：

• 包：mcp-mail-server

• Node.js：≥18.0.0

• 仓库：GitHub

• 问题：报告问题