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
配置
- 编辑
.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
- 确保 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/ # 日志目录（自动创建）
🔧 配置说明
环境变量
| 变量名 | 说明 | 默认值 | 必需 |
|--------|------|--------|------|
| CHATLOG_BASE_URL | Chatlog API 服务地址 | http://127.0.0.1:5030 | ✅ |
| DEFAULT_DOWNLOAD_DIR | 默认下载目录 | /tmp/chatlog-downloads | ❌ |
| PERPLEXITY_API_KEY | Perplexity API 密钥 | - | ❌ |
下载目录
如果未指定 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
贡献
- Fork 项目
- 创建特性分支 (
git checkout -b feature/AmazingFeature)
- 提交更改 (
git commit -m 'Add some AmazingFeature')
- 推送到分支 (
git push origin feature/AmazingFeature)
- 打开 Pull Request
📄 许可证
本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。
🤝 支持
... View full README on GitHub
