Chatlog MCP Server

一个专为 Claude Code CLI 设计的聊天记录 MCP 服务器，支持直接下载微信聊天中的媒体文件到本地存储。

✨ 主要特性

• 🔍 聊天记录查询: 支持按时间、发送者、关键词筛选聊天记录
• 📥 直接下载: 图片、语音、视频、文件直接下载到本地
• 🗂️ 智能管理: 自动创建目录结构，避免文件冲突
• 🛡️ 安全可靠: 完善的错误处理和超时保护
• 🔧 简单配置: 最小化配置，开箱即用

🚀 快速开始

系统要求

• Node.js >= 16.0.0
• Claude Code CLI
• Chatlog API 服务运行中

一键安装

Linux/macOS:

curl -sSL https://raw.githubusercontent.com/yourusername/wechatlog-mcp-server/main/install.sh | bash

Windows:

powershell -Command "& { iwr https://raw.githubusercontent.com/yourusername/wechatlog-mcp-server/main/install.bat | Out-String | Invoke-Expression }"

手动安装:

# 克隆项目
git clone https://github.com/yourusername/wechatlog-mcp-server.git
cd wechatlog-mcp-server

# 运行安装脚本
./install.sh

# 或使用 Node.js 安装
node install.js

配置

1. 编辑 .env 文件：

CHATLOG_BASE_URL=http://127.0.0.1:5030
DEFAULT_DOWNLOAD_DIR=/tmp/chatlog-downloads  # 默认下载目录（绝对路径）
PERPLEXITY_API_KEY=your_perplexity_api_key_here  # 可选

注意: DEFAULT_DOWNLOAD_DIR 必须是绝对路径，例如：

• Linux/macOS: /home/user/downloads
• macOS: /Users/username/Downloads
• Windows: C:\Users\username\Downloads

2. 确保 Chatlog API 服务运行在指定地址

注册到 Claude

claude mcp add chatlog node chatlog-mcp-server.js

📚 使用方法

基础命令

# 启动服务器
npm start

# 运行测试
npm test

# 查看帮助
claude mcp list

可用工具

📋 聊天记录管理

• queryChatLog - 查询指定聊天对象的聊天记录
• getContactList - 获取微信联系人列表
• getChatroomList - 获取微信群聊列表
• getSessionList - 获取会话列表

📥 媒体文件下载

• downloadImage - 下载图片文件
• downloadVoice - 下载语音消息
• downloadVideo - 下载视频文件
• downloadFile - 下载其他文件

🔧 系统工具

• healthCheck - 检查服务状态
• accessDataFile - 访问数据文件

📁 项目结构

chatlog-mcp/
├── chatlog-mcp-server.js    # 主服务器文件
├── package.json              # 项目配置
├── install.js               # Node.js 安装脚本
├── install.sh               # Linux/macOS 安装脚本
├── install.bat              # Windows 安装脚本
├── test-chatlog-mcp.sh      # 测试脚本
├── .env.example             # 环境变量模板
├── .env                     # 环境配置（安装后生成）
├── downloads/               # 下载目录（自动创建）
└── logs/                    # 日志目录（自动创建）

🔧 配置说明

环境变量

下载目录

如果未指定 saveDir 参数，媒体文件将下载到 DEFAULT_DOWNLOAD_DIR 环境变量指定的目录：

• 默认目录: /tmp/chatlog-downloads/
• 也可指定任意绝对路径作为 saveDir 参数

🧪 测试

运行内置测试脚本：

./test-chatlog-mcp.sh

或使用 npm：

npm test

📝 示例用法

查询聊天记录

// 查询今天与文件传输助手的聊天
mcp__wechatlog__queryChatLog({
  talker: "filehelper",
  time: "2025-09-24"
})

下载最新图片

// 下载图片到指定目录（可选，如不指定将使用环境变量中的默认目录）
mcp__wechatlog__downloadImage({
  id: "595f549d393e960a64b9a4883a6dd1fe",
  saveDir: "/Users/username/Downloads",  // 可选，绝对路径
  fileName: "my-image.jpg"
})

// 或使用默认目录
mcp__wechatlog__downloadImage({
  id: "595f549d393e960a64b9a4883a6dd1fe",
  fileName: "my-image.jpg"
})

获取联系人列表

// 搜索特定联系人
mcp__wechatlog__getContactList({
  keyword: "张三",
  limit: 10,
  offset: 0,
  format: "json"
})

🛠️ 开发

本地开发

# 克隆项目
git clone https://github.com/LupinLin1/chatlog-mcp-server.git
cd chatlog-mcp-server

# 安装依赖（无外部依赖）
npm install

# 开发模式运行
npm start

贡献

1. Fork 项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🤝 支持

• 🐛 问题反馈: GitHub Issues
• 💬 讨论交流: GitHub Discussions
• 📧 邮件联系: [email protected]

🔗 相关链接

• Claude Code CLI 文档
• Model Context Protocol 规范
• Chatlog API 文档

---

⭐ 如果这个项目对您有帮助，请给它一个星标！