wx-cli/USAGE.md

# Usage Examples / 使用案例

WeChat MCP Server 注册到 Claude Code 后，可以直接在对话中查询微信数据。以下是真实使用截图（敏感信息已打码）。

## 1. 查看最近会话

```
> 帮我看看微信最近的会话
```

Claude 自动调用 `get_recent_sessions`：

```
最近 10 个会话:

[02-28 16:26] A]██交流群 [群] (7条未读)
  文本: 阿██: 打开就是那么大的一个

[02-28 16:26] ██俱乐部 [群] (105条未读)
  文本: S██: 死了就换另外一个

[02-28 16:26] ██Sol██社区 [群] (3条未读)
  文本: 洋██: 加密币已成中登资产，还没避险属性

[02-28 16:25] ██健身群 [群] (18条未读)
  文本: 风██: 不强求，多的就留着。刚需就洗了。

[02-28 16:24] ██社保 (24条未读)
  链接/文件: @年后换工作的你，社保怎么处理？看这里！

[02-28 16:22] 文件传输助手
  图片: (无内容)
```

## 2. 查看群聊记录

```
> 帮我看看██群在聊啥
```

Claude 调用 `get_chat_history`，然后自动分析总结：

```
██群今日话题:

1. AI工具讨论 (上午)
   群友对微信消息监听工具感兴趣，问了用什么模型、token贵不贵。

2. A股炒股 (下午)
   ██想让朋友帮操作A股做T，群友一致劝阻——"赚了分他，亏了算你的"

3. 基金持仓 (傍晚)
   ██手痒又买了有色基金

活跃度排名:
| 排名 | 昵称 | 发言数 |
|------|------|--------|
| 1 | ██ | ~35条 |
| 2 | ██ | ~15条 |
| 3 | ██ | ~15条 |
```

## 3. 搜索消息

```
> 搜一下谁提过"claude"
```

Claude 调用 `search_messages(keyword="claude")`：

```
搜索 "claude" 找到 20 条结果:

[2026-02-28 10:25] [██AI群] ██: max套餐，就用opus模型
[2026-02-28 10:31] [██AI群] ██: 我小龙虾也没用api接入的
[2026-02-24 21:58] [██AI群] ██: Claude max 套餐给我干没了
[2026-02-24 22:16] [██AI群] ██: 最简单的就是装claude
...
```

## 4. 时间范围 + 分页查看聊天记录

```
> 帮我看一下██群 3 月 1 日到 3 月 7 日的聊天，先给我前 20 条
```

Claude 可以调用：

```python
get_chat_history(
    chat_name="██群",
    start_time="2026-03-01",
    end_time="2026-03-07",
    limit=20,
    offset=0,
)
```

下一页：

```python
get_chat_history(
    chat_name="██群",
    start_time="2026-03-01",
    end_time="2026-03-07",
    limit=20,
    offset=20,
)
```

## 5. 搜索指定联系人/群聊在某个时间段内的消息

```
> 帮我搜一下██群这周谁提到过 Claude
```

Claude 可以调用统一接口：

```python
search_messages(
    keyword="Claude",
    chat_name="██群",
    start_time="2026-03-01",
    end_time="2026-03-07",
    limit=20,
    offset=0,
)
```

## 6. 多个联系人/群聊联合搜索

```
> 帮我看看联系人A、联系人B 和 ██项目群 这周谁提到过“项目”
```

Claude 可以调用统一接口：

```python
search_messages(
    keyword="项目",
    chat_name=["联系人A", "联系人B", "██项目群"],
    start_time="2026-03-01",
    end_time="2026-03-07",
    limit=20,
    offset=0,
)
```

如果某些名字没匹配到联系人，或没有对应消息表，结果里会单独说明。

## 7. 搜索联系人

```
> 帮我找一下姓张的联系人
```

Claude 调用 `get_contacts(query="张")`：

```
找到 12 个联系人（搜索: 张）:

wxid_████  备注: 张██  昵称: ██
wxid_████  备注: 张██  昵称: 小██
████@chatroom  昵称: 张██的工作群
...
```

## 8. 获取新消息

```
> 有没有新消息
```

Claude 调用 `get_new_messages()`：

```
当前 5 个未读会话:

[16:26] ██交流群 [群] (7条未读): 打开就是那么大的一个
[16:26] ██俱乐部 [群] (105条未读): 死了就换另外一个
[16:25] ██健身群 [群] (18条未读): 不强求，多的就留着
[16:24] ██社保 (24条未读): @年后换工作的你...
[16:22] ██群 [群] (19条未读): (图片)
```

## 9. 高级用法：群聊分析

Claude 可以获取大量消息后自动分析活跃度、话题分布、关键人物：

```
> 帮我分析一下██群最近一周的情况
```

Claude 会调用 `get_chat_history(chat_name="██群", limit=500)` 获取消息，然后输出。消息很多时，也可以把 `limit` 设得更大，或配合 `offset` 分页读取：

```
## ██群最近一周分析

### 话题分布
| 话题     | 占比  |
|----------|-------|
| AI工具   | ~40%  |
| 币圈行情 | ~25%  |
| 时事讨论 | ~20%  |
| 闲聊     | ~15%  |

### 活跃度排名
| 排名 | 昵称 | 发言数 | 角色       |
|------|------|--------|------------|
| 1    | ██   | ~90条  | 技术分享者 |
| 2    | ██   | ~55条  | 深度讨论   |
| 3    | ██   | ~25条  | 新闻搬运   |

### 群氛围
这个群正在从██交流群转型成AI工具交流群...
```

---

## Setup / 配置方法

```bash
# 1. 安装依赖
pip install -r requirements.txt

# 2. 注册到 Claude Code
claude mcp add wechat -- python C:\path\to\mcp_server.py

# 3. 在 Claude Code 中直接对话
claude
> 看看微信最近谁找我了
```

前置条件：需要先运行 `find_all_keys.py` 提取密钥，并配置 `config.json`。详见 [README.md](README.md)。