# Wechatlog Mcp Server

> WeChat Chatlog MCP Server - 直接下载微信聊天媒体文件到本地

- **Type:** MCP server
- **Install:** `agentstack add mcp-lupinlin1-wechatlog-mcp-server`
- **Verified:** Pending review
- **Seller:** [LupinLin1](https://agentstack.voostack.com/s/lupinlin1)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [LupinLin1](https://github.com/LupinLin1)
- **Source:** https://github.com/LupinLin1/wechatlog-mcp-server

## Install

```sh
agentstack add mcp-lupinlin1-wechatlog-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Chatlog MCP Server

[](https://nodejs.org/)
[](LICENSE)

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

## ✨ 主要特性

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

## 🚀 快速开始

### 系统要求

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

### 一键安装

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

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

**手动安装:**
```bash
# 克隆项目
git clone https://github.com/yourusername/wechatlog-mcp-server.git
cd wechatlog-mcp-server

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

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

### 配置

1. 编辑 `.env` 文件：
```bash
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

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

## 📚 使用方法

### 基础命令

```bash
# 启动服务器
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` 参数

## 🧪 测试

运行内置测试脚本：

```bash
./test-chatlog-mcp.sh
```

或使用 npm：

```bash
npm test
```

## 📝 示例用法

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

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

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

### 获取联系人列表
```javascript
// 搜索特定联系人
mcp__wechatlog__getContactList({
  keyword: "张三",
  limit: 10,
  offset: 0,
  format: "json"
})
```

## 🛠️ 开发

### 本地开发

```bash
# 克隆项目
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](LICENSE) 文件了解详情。

## 🤝 支持

- 🐛 **问题反馈**: [GitHub Issues](https://github.com/LupinLin1/chatlog-mcp-server/issues)
- 💬 **讨论交流**: [GitHub Discussions](https://github.com/LupinLin1/chatlog-mcp-server/discussions)
- 📧 **邮件联系**: your-email@example.com

## 🔗 相关链接

- [Claude Code CLI 文档](https://docs.anthropic.com/claude/docs/claude-code)
- [Model Context Protocol 规范](https://modelcontextprotocol.io/)
- [Chatlog API 文档](./chatlog-openapi.yaml)

---

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

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [LupinLin1](https://github.com/LupinLin1)
- **Source:** [LupinLin1/wechatlog-mcp-server](https://github.com/LupinLin1/wechatlog-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-lupinlin1-wechatlog-mcp-server
- Seller: https://agentstack.voostack.com/s/lupinlin1
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.