QQ邮箱搜索MCP工具

这是一个基于MCP（Model Context Protocol）的工具，用于搜索QQ邮箱内容并将结果保存到本地磁盘的Excel文件中。

功能特点

• 连接QQ邮箱IMAP服务器，搜索邮件内容
• 支持按发件人、主题、日期范围进行搜索
• 将搜索结果导出为Excel表格
• 简洁直观的图形用户界面
• 作为MCP服务器，可与支持MCP协议的AI助手集成

系统要求

• Node.js 14.0.0 或更高版本
• npm 6.0.0 或更高版本
• Windows、macOS 或 Linux 操作系统

安装步骤

1. 克隆或下载本项目到本地
2. 进入项目目录，安装依赖：

cd qq-email-search-mcp
npm install

使用方法

启动应用

有多种方式启动应用：

方式1：使用启动脚本（推荐）

• Windows用户：双击start.bat文件
• macOS/Linux用户：

  chmod +x start.sh  # 添加执行权限（仅首次需要）
  ./start.sh
  

方式2：使用命令行

node start.js

或者：

npm start

以上方法都会同时启动MCP服务器和图形界面。

使用图形界面

1. 输入QQ邮箱地址和授权码（不是QQ密码）
2. 设置搜索条件（可选）：
   • 发件人邮箱地址
   • 邮件主题关键词
   • 日期范围
3. 点击"搜索邮件"按钮
4. 查看搜索结果
5. 点击"导出Excel"按钮，选择保存位置

获取QQ邮箱授权码

1. 登录QQ邮箱网页版
2. 点击"设置" -> "账户"
3. 在"POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务"下，开启"IMAP/SMTP服务"
4. 根据提示生成授权码
5. 详细说明请参考QQ邮箱帮助中心

作为MCP服务器使用

本工具可以作为MCP服务器，提供以下工具：

1. search_qq_email

搜索QQ邮箱内容。

参数：

• email: QQ邮箱地址（必需）
• auth_code: QQ邮箱授权码（必需）
• sender: 发件人筛选（可选）
• subject: 主题筛选（可选）
• start_date: 开始日期，格式YYYY-MM-DD（可选）
• end_date: 结束日期，格式YYYY-MM-DD（可选）

2. export_to_excel

将搜索结果导出为Excel文件。

参数：

• search_results: 搜索结果数组（必需）
• file_path: 保存Excel文件的路径（必需）

日志文件

应用运行日志保存在logs目录下：

• server.log: MCP服务器日志
• ui.log: 用户界面日志

故障排除

1. 无法连接到QQ邮箱

   • 确认QQ邮箱地址和授权码正确
   • 确认已开启IMAP服务
   • 检查网络连接

2. 搜索结果为空

   • 尝试放宽搜索条件
   • 确认邮箱中确实存在符合条件的邮件

3. 导出Excel失败

   • 确认选择的保存位置有写入权限
   • 确保Excel文件未被其他程序占用

4. 启动应用时出现"spawn electron ENOENT"错误

   • 这通常是因为Electron没有正确安装
   • 运行npm install确保所有依赖都已安装
   • 如果问题仍然存在，尝试全局安装Electron: npm install -g electron

5. Windows系统上的特殊问题

   • 如果在Windows系统上遇到路径相关的错误，请确保使用正确的路径分隔符
   • 某些情况下可能需要以管理员权限运行命令提示符或PowerShell

许可证

MIT