JinDaGe - mcp-mail-server MCP Details

article

README

🚀 MCP邮件服务器

MCP邮件服务器是一个用于IMAP/SMTP邮件操作的模型上下文协议服务器，可与Claude、Cursor等AI助手协同工作，帮助用户更便捷地管理和操作邮件。

🚀 快速开始

安装：使用命令 npm install -g mcp-mail-server 进行全局安装。
配置：配置环境变量（详见配置说明）。
添加：将其添加到你的MCP客户端配置中。
使用：通过自然语言指令操作，例如 "Show me unread emails from today"。

✨ 主要特性

IMAP操作：可在多个邮箱中搜索、读取和管理邮件。
SMTP支持：支持发送包含HTML或纯文本内容以及附件的邮件。
安全配置：基于环境变量进行设置，支持TLS/SSL加密。
AI友好：支持使用自然语言命令进行邮件操作。
自动连接管理：自动处理IMAP和SMTP连接。
多邮箱支持：可访问收件箱、已发送邮件和自定义文件夹。

📦 安装指南

Claude桌面版

在 claude_desktop_config.json 文件中添加以下配置：

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["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

在Cursor的MCP设置中添加以下配置：

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["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客户端

进行全局安装：

npm install -g mcp-mail-server

然后进行如下配置：

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "mcp-mail-server"
    }
  }
}

📚 详细文档

可用工具

| 工具 | 描述 | |------|-------------| | connect_all | 连接到IMAP和SMTP服务器 | | get_connection_status | 检查连接状态和服务器信息 | | disconnect_all | 断开与所有服务器的连接 | | open_mailbox | 打开指定的邮箱或文件夹 | | list_mailboxes | 列出可用的邮件文件夹 | | search_messages | 根据IMAP条件搜索邮件 | | search_by_sender | 查找特定发件人的邮件 | | search_by_subject | 根据主题关键词搜索邮件 | | search_by_body | 搜索邮件内容 | | search_since_date | 查找指定日期之后的邮件 | | search_unreplied_from_sender | 查找特定发件人未回复的邮件 | | search_larger_than | 根据邮件大小查找邮件 | | get_message | 根据UID检索邮件 | | get_messages | 检索多封邮件 | | delete_message | 根据UID删除邮件 | | get_unseen_messages | 获取所有未读邮件 | | get_recent_messages | 获取最近的邮件 | | send_email | 通过SMTP发送邮件 | | reply_to_email | 回复特定邮件 |

详细工具参数

连接管理

connect_all：无需参数
get_connection_status：无需参数
disconnect_all：无需参数

邮箱操作

open_mailbox：mailboxName（字符串，默认值："INBOX"），readOnly（布尔值）
list_mailboxes：无需参数

搜索操作

search_messages：criteria（数组，IMAP搜索条件）
search_by_sender：sender（字符串，电子邮件地址）
search_by_subject：subject（字符串，关键词）
search_by_body：text（字符串，搜索文本）
search_since_date：date（字符串，日期格式）
search_unreplied_from_sender：sender（字符串，电子邮件地址），startDate（字符串，可选），endDate（字符串，可选）
search_larger_than：size（数字，字节）

邮件操作

get_message：uid（数字），markSeen（布尔值，可选）
get_messages：uids（数组），markSeen（布尔值，可选）
delete_message：uid（数字）

邮件发送

send_email：to（字符串），subject（字符串），text（字符串，可选），html（字符串，可选），cc（字符串，可选），bcc（字符串，可选）
reply_to_email：originalUid（数字），text（字符串），html（字符串，可选），replyToAll（布尔值，可选），includeOriginal（布尔值，可选）

💻 使用示例

基础用法

可以通过向AI助手输入自然语言命令来操作邮件，例如：

"Connect to my email servers"
"Show me all unread emails"
"Search for emails from boss@company.com"
"Send an email to team@company.com about the meeting"
"Reply to email with UID 123"

高级用法

"Find emails with 'urgent' in the subject from last week"
"Show me unreplied emails from boss@company.com"
"Show me large emails over 5MB"
"Get all emails from the Sales folder"

邮件管理

"Delete the email with UID 123"
"Mark recent emails as read"
"List all my email folders"

🔧 技术细节

配置环境变量

⚠️ 重要提示

所有环境变量均为必填项。

| 属性 | 详情 | 示例 | |------|------|------| | IMAP_HOST | IMAP服务器地址 | imap.gmail.com | | IMAP_PORT | IMAP端口号 | 993 | | IMAP_SECURE | 启用TLS | true | | SMTP_HOST | SMTP服务器地址 | smtp.gmail.com | | SMTP_PORT | SMTP端口号 | 465 | | SMTP_SECURE | 启用SSL | true | | EMAIL_USER | 邮箱用户名 | your-email@gmail.com | | EMAIL_PASS | 邮箱密码或应用密码 | your-app-password |

常见邮箱提供商配置

Gmail配置

```bash 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 ``` > ⚠️ **重要提示** > > 请使用 [应用密码](https://support.google.com/accounts/answer/185833) 而非常规密码。

Outlook/Hotmail配置

```bash 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并使用应用专用密码。

始终使用安全连接（IMAP_SECURE=true，SMTP_SECURE=true）。

切勿在配置文件中硬编码凭证信息。

本地开发设置

克隆仓库：

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

安装依赖：

npm install

构建项目：

npm run build

设置环境变量：

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

启动服务器：

npm start

📄 许可证

本项目采用MIT许可证，详情请参阅 LICENSE 文件。

包信息：

包名：mcp-mail-server
Node.js版本：≥18.0.0
仓库地址：GitHub
问题反馈：报告问题

mcp-mail-server