# im-mcp (本地绿泡泡 & DuangDuang AI 检索 MCP Server)

基于 **Model Context Protocol (MCP)** 规范构建的本地 IM（绿泡泡 & DuangDuang）聊天记录与通讯录检索服务。
极简、只读、完全离线本地运行，让 Claude Desktop、Cursor、Cline、Pi 等 AI Agent 能够安全、高速地检索与总结你的工作沟通、群聊记录和知识库。

> 💡 **复制即用提示词（直接发给你的 AI Agent / 客户端）**：
> 
> ```text
> 请阅读并遵循开源项目 https://github.com/stkoecn/im-mcp 中的 README.md 与 skills/im-mcp/SKILL.md，帮我配置并启用本机的绿泡泡与DuangDuang MCP 服务。
> ```

> 注：原底层参考项目以 Git Submodule 形式统一归档在 `reference/` 目录下（`reference/wechat-local-viewer` 与 `reference/dingwave-V3`）。

---

## ✨ 核心特性

- ⚡ **超低延迟**：直接基于本地解密 SQLite 数据库，毫秒级响应。
- 🔒 **纯本地与只读**：所有数据均在本地，绝不上云；以只读方式运行，不破坏原始数据。
- 📦 **按需安装（Optional Dependencies）**：一个仓库，两套独立入口；支持只装绿泡泡、只装DuangDuang或全量安装。
- 💬 **丰富格式解析**：
  - **绿泡泡**：支持普通文本、引用消息、富文本卡片、小程序、传输文件（PDF/Excel/Word等）。
  - **DuangDuang**：支持多表分片聚合（`tbmsg_000`~`tbmsg_127`）、联系人实名映射、Markdown卡片、协同日程通知、文件附件提取。

---

## 🔍 支持的客户端与系统版本 (Compatibility)

| 平台 | 支持版本范围 | 实测验证版本 | 架构与平台 | 解密 / 同步原理 |
|---|---|---|---|---|
| **绿泡泡 (WeChat)** | **绿泡泡 4.x** 全系列<br>*(兼容 3.9.x)* | **`4.1.15.13`** (Windows 最新版)<br>**`4.1.35.15`** (macOS ARM64 最新版)<br>**`4.1.15` (270115)** (macOS x86_64 实测验证)<br>`4.1.11.x` 等 | Windows x64<br>macOS (Apple Silicon & Intel) | **Windows**: 运行时扫描 `Weixin.exe` Config.Cipher 动态提取 Salt 密钥；<br>**macOS**: 原生 `CommonCrypto` (CCCrypt) 零额外依赖解密，支持 passphrase PBKDF2 派生；离线 HMAC 校验并解密 WCDB SQLite |
| **DuangDuang (DingTalk)** | **DuangDuang 7.x** 全系列<br>*(涵盖 V2 与 V3)* | **`7.6.0.x`** (最新版)<br>`7.5.x` / `7.0.x` | Windows x64 / macOS | 纯离线读取用户目录 `user_config`，通过 PBKDF2-HMAC-SHA1 + MD5 推导 AES-128 密钥并合并 WAL 事务 |

---

## 🧰 提供的 MCP Tools

### 1. 绿泡泡 (`wechat-mcp`)

共 29 个工具，全部只读（`sync_wechat_database` / `start_sync` / `set_auto_sync` 会触发本地快照重建，但不向微信发送任何消息）。

> 本 fork 相对上游新增 / 修复的完整清单见 [CHANGELOG.md](./CHANGELOG.md)。

**消息检索**

| 工具名称 | 说明 | 适用场景 |
|---|---|---|
| `search_wechat_messages` | 全文检索聊天消息（多词 AND，可限定会话 / 发言人 / 时间窗，支持 `offset` 分页；每条带 `snippet` 命中上下文） | “找一下群里谁发过关于‘某某需求’的讨论” |
| `get_session_history` | 获取指定会话的最近对话（时间正序，可限定天数） | “总结一下这个项目群最近 50 条消息都在聊什么” |
| `get_messages_by_date` | 按指定日期拉取全量或限定会话记录（支持 `offset` 分页） | “帮我汇总 2026-10-16 那天所有沟通做日报” |
| `get_messages_by_range` | 按自定义时间范围（支持跨天与任意时段、按人过滤、`offset` 分页）拉取记录 | “拉一下上周三到周五这个群聊了什么” |
| `get_messages_since` | 增量游标：只取 `after_id` / `after_time` 之后的新消息，返回 `next_cursor` 与 `has_more` | “面板刷新新消息 / 脚本增量同步，不重复拉全量” |

**会话与通讯录**

| 工具名称 | 说明 | 适用场景 |
|---|---|---|
| `list_wechat_sessions` | 查询群聊或联系人列表（获取唯一 ID，含未读快照 `unread`） | “帮我看看关于‘量化’有哪些群” |
| `get_unread_sessions` | 列出有未读消息的会话（按最近活跃倒序） | “还有哪些群没看” |
| `get_session_overview` | 单个会话的轻量概览（累计条数 / 范围消息量 / 发言人数 / 峰值时段 / 类型 TopN / 首末时间） | “切群先看一眼这个群多大、什么时候最热” |
| `search_contacts` | 按昵称 / 备注 / 微信号搜索联系人 | “查一下张工的微信号和备注名” |
| `list_chatroom_members` | 列出指定群聊的成员名单（自动关联昵称与微信号） | “这个群一共多少人，都有谁” |

**文件 / 图片 / 媒体 / 收藏 / 表情**

| 工具名称 | 说明 | 适用场景 |
|---|---|---|
| `get_message_image` | 按消息 ID 定位并按需解密聊天图片（支持本地物理路径或多模态 Base64） | “把刚才查到的那张聊天图片解密提取出来看下” |
| `get_chat_record` | 展开「聊天记录」合并转发消息，把被合并的正文解析为结构化条目（文本 / 图片 / 视频 / 文件） | “这条『聊天记录』里到底转了些什么” |
| `get_user_avatars` | 批量取用户 / 群 / 公众号头像的本地图片路径（供面板等宿主直接读盘渲染，不返回 base64） | “把群里发言者的头像都给我” |
| `search_shared_files` | 查找聊天中发送/接收的文件文档 | “找一下上周有人发在群里的那个理财报告 Excel” |
| `search_media_files` | 查找聊天中的图片 / 文件 / 视频及其磁盘路径 | “把群里发过的截图路径给我” |
| `list_favorites` | 查询绿泡泡收藏条目（标题 / 描述 / 来源） | “我收藏过哪些资料” |
| `list_emoticons` | 列出表情包与表情（含官方文字说明） | “那个‘偷听’表情在哪个包里” |
| `prepare_emoticons` | 生成 / 刷新本地明文表情库（调用外部 `wxemo` 完成一次性 GPU 搜索，把 `business/emoticon` 下的账号级加密表情摊平成 `~/.wechat_mcp/emoticons/<md5>.<ext>`） | “让表情能直接出图” / 首次启用表情取图能力 |
| `get_emoticon_image` | 按表情 md5 取本地明文表情图的文件路径（gif / png / jpg / webp / APNG；md5 来自消息返回的 `emoticon_md5`） | “把这条 `[表情]` 消息的那个表情图给我” |
| `extract_image_key` | 从运行中的绿泡泡进程内存提取 **V2 图片解密密钥**并写入密钥文件（`image_aes_key` 字段）；需先在客户端点开 1-2 张图片再立刻调用 | “V2 聊天图片解密报缺 `image_aes_key`，把密钥取出来” |

**分析与同步**

| 工具名称 | 说明 | 适用场景 |
|---|---|---|
| `get_chat_activity_stats` | 聊天活跃度全量聚合（消息/发言人数、小时与日分布、跨天 `hourly_series`、类型分布、参与度分桶、会话片段、集中度、成员多维榜、引用网络、撤回事件） | “这个群什么时候最活跃” |
| `get_group_digest` | 群聊日报/周报所需的聚合数据（= activity stats + 金句候选 `highlights`） | “给这个群出一份日报 / 周报” |
| `get_member_profile` | 单个成员的群聊画像（活跃节奏、内容结构、互动对象；可选附带最近 N 条原文 `include_samples`） | “分析群里这个人的发言风格与关注点” |
| `get_persona_style` | 分析某位联系人的沟通风格（画像 + 高频用语 + 典型语句） | “模仿一下这个人的说话风格” |
| `get_sync_status` | 查看本地索引的新鲜度与规模，判断是否需要重新同步 | “数据是不是最新的” |
| `sync_wechat_database` | 阻塞式同步：**先重新解密源库**、再重建本地索引（只重建索引拿不到新消息） | “刚聊了几句，帮我更新一下数据库后再查” |
| `start_sync` | 后台同步（立即返回，用 `get_auto_sync_status` 轮询）—— 绕过宿主单次调用 120s 超时 | “面板里点‘同步’但别把界面卡死” |
| `set_auto_sync` | 开启 / 关闭定时同步（重新解密 + 重建索引），状态持久化、服务重启后自动恢复 | “每半小时自动同步一次微信数据” |
| `get_auto_sync_status` | 查看定时同步的开关、间隔、运行次数与上次结果 | “定时同步到底有没有在跑” |

### 2. DuangDuang (`dingtalk-mcp`)

| 工具名称 | 说明 | 适用场景 |
|---|---|---|
| `search_dingtalk_messages` | 全文检索DuangDuang消息（支持按群/私聊过滤） | “搜一下DuangDuang里成鹏发过的报表统计结果” |
| `list_dingtalk_conversations` | 列出DuangDuang最近会话（自动解析群名与实名） | “看看DuangDuang里最近活跃的项目组群” |
| `get_dingtalk_messages` | 获取指定DuangDuang会话的历史消息上下文 | “拉取‘定制报表项目组’最近的历史消息” |
| `list_dingtalk_contacts` | 查询团队通讯录与联系人（手机号、邮箱、真名） | “查一下DuangDuang里某个同事的联系方式” |
| `sync_dingtalk_data` | 自动拷贝DuangDuang数据库并执行 WAL 解密同步 | “重新同步最新的DuangDuang聊天记录” |

---

## 📦 安装与运行方式

本项目已完整遵循 PEP 517 / 621 标准打包，原生支持 **`uv` / `uvx`** 以及 `pip`，免手动配置虚拟环境与路径。

### 1. 推荐：通过 `uv tool install` 全局隔离安装（最推荐，一次安装全局可用）

使用 `uv tool` 会为工具创建独立受控的持久化运行环境，并将 CLI 注册到系统全局路径，**之后无需重复拉取，启动极快**：

```bash
# 全局安装 CLI 工具链 (wechat-init, dingtalk-init, wechat-mcp, dingtalk-mcp, im-clean)
uv tool install "git+https://github.com/stkoecn/im-mcp.git" --with "im-mcp[all]"
# （国内网络用户亦可使用 Gitee 源：uv tool install "git+https://gitee.com/ws4m/im-mcp.git" --with "im-mcp[all]"）

# 后续如需更新到最新版本，仅需执行：
uv tool upgrade im-mcp
```

### 2. 备选：通过 `uvx` 即席运行（临时/测试体验）

`uvx` 适合一次性临时体验或不想常驻安装的场景（每次可能存在版本检查开销；国内环境可替换为 `git+https://gitee.com/ws4m/im-mcp.git[all]`）：

```bash
# 直接免安装即席运行初始化
uvx --from "git+https://github.com/stkoecn/im-mcp.git[all]" dingtalk-init
uvx --from "git+https://github.com/stkoecn/im-mcp.git[all]" wechat-init
```

### 3. 传统 `pip` 安装（支持按需依赖）

```bash
# 两个平台都需要（全量）
pip install "git+https://github.com/stkoecn/im-mcp.git#egg=im-mcp[all]"

# 只需要绿泡泡
pip install "git+https://github.com/stkoecn/im-mcp.git#egg=im-mcp[wechat]"

# 只需要DuangDuang
pip install "git+https://github.com/stkoecn/im-mcp.git#egg=im-mcp[dingtalk]"
```

---

## 🤖 智能体配套技能文档 (Agent Skills)

本项目在 [`skills/im-mcp/SKILL.md`](skills/im-mcp/SKILL.md) 中完整定义了面向各平台 AI Agent（Pi、Claude Desktop/Code、Cursor、Cline 等）的完整自动化运维规范（涵盖**依赖运行策略、初始化前置检查、MCP 工具链调用 SOP、异常处置禁令及附录参考目录**）。

### 安装方式：直接复制到当前 Agent 技能目录

- **通用智能体环境 (Pi / Codex / Pebrel)**：
  ```bash
  mkdir -p ~/.agents/skills/im-mcp && cp skills/im-mcp/SKILL.md ~/.agents/skills/im-mcp/
  ```
- **Claude Code / Desktop**：
  ```bash
  mkdir -p ~/.claude/skills/im-mcp && cp skills/im-mcp/SKILL.md ~/.claude/skills/im-mcp/
  ```
- **当前项目工作区本地生效**：
  ```bash
  mkdir -p .agents/skills/im-mcp && cp skills/im-mcp/SKILL.md .agents/skills/im-mcp/
  ```

---

## 🛠️ 开箱即用：一键初始化 CLI (`wechat-init` & `dingtalk-init`)

安装本包后，系统会自动注册两个专用的命令行初始化向导。在日常使用 AI 客户端连接前，只需在控制台**运行一次**即可完成密钥提取与数据库初始化：

### 1. 绿泡泡一键初始化 (`wechat-init`)
> **注意**：
> - **Windows**：由于需要读取绿泡泡客户端内存（安全校验与运行时 Cipher 扫描），请确保**以管理员身份打开终端**，并且**Windows 绿泡泡已登录**。
> - **macOS**：支持自动检测数据目录 `~/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/*/db_storage`；微信 4.1+ 可通过 `--passphrase <64位hex>` 传入或由 `wechat-passphrase.json` 持久化，采用系统原生 `CommonCrypto` 完成 256,000 轮 PBKDF2 派生与全库零依赖极速解密。

```bash
# Windows: 一键提取密钥、解密为 SQLite 并自动构建 FTS5 全文索引（默认保存至 ~/.wechat_mcp/）
wechat-init

# macOS (微信 4.1+ 配合 passphrase):
wechat-init --passphrase <64位十六进制passphrase>

# 高级选项（跨平台通用）
wechat-init --output ~/.wechat_mcp/decrypted   # 指定解密数据库保存路径（默认 ~/.wechat_mcp/decrypted）
wechat-init --only-extract                     # 仅提取密钥保存至 all_keys.json，不立即解密
wechat-init --etl-only                         # 仅执行数据清洗与重构 FTS5 索引（无需重复解密）
```

### 2. DuangDuang一键初始化 (`dingtalk-init`)
> DuangDuang采用纯 Python 本地解密算法（支持 V2/V3 及 WAL 事务合并），自动查找当前登录的 UID，普通用户终端即可执行：

```bash
# 一键同步并解密当前登录DuangDuang的数据库
dingtalk-init

# 高级选项（可选）
dingtalk-init --output-dir ~/.dingtalk_mcp/decrypted  # 指定输出路径
```

---

## 🧹 一键清理工具 (`im-clean`)

如果在测试或使用后需要清理导出的明文 SQLite 数据库、密钥文件及 FTS 中间缓存，可以使用 `im-clean` 一键彻底清理：

```bash
# 1. 模拟预览（只查看待清理文件与磁盘占用，不真正删除）
im-clean --dry-run

# 2. 交互式安全清理（支持二次确认）
im-clean

# 3. 按需清理指定平台
im-clean --scope wechat      # 仅清理绿泡泡导出的数据与密钥
im-clean --scope dingtalk    # 仅清理DuangDuang导出的数据与缓存

# 4. 静默全量删除（适合自动化脚本）
im-clean -y
```

---

## 🚀 客户端接入配置 (Claude Desktop / Cursor / Pi)

### 方案 A：使用 `uvx` 即席运行（零环境污染，免手动建 venv，最推荐）

客户端通过 `uvx` 动态拉取执行，并在 `env` 中显式固化全局数据目录，杜绝工作目录变动影响：

```json
{
  "mcpServers": {
    "wechat": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/stkoecn/im-mcp.git[all]",
        "wechat-mcp"
      ],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUTF8": "1"
      },
      "description": "绿泡泡聊天记录与群聊检索 MCP"
    },
    "dingtalk": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/stkoecn/im-mcp.git[all]",
        "dingtalk-mcp"
      ],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUTF8": "1"
      },
      "description": "DuangDuang聊天记录、群聊与通讯录检索 MCP"
    }
  }
}
```

### 方案 B：全局 `uv tool` 运行（一次安装，秒级冷启动）

若当前环境未受沙箱拦截，且已执行 `uv tool install "git+https://github.com/stkoecn/im-mcp.git" --with "im-mcp[all]"`，直接使用系统 PATH 中的命令：

> 💡 **PATH 说明**：若安装后 uv 提示 `warning: ... is not on your PATH`，可运行 `uv tool update-shell`（或重启终端生效）。在严格安全限制无法修改 PATH 的环境下，亦可直接使用绝对路径配置（例如 Windows 下填写 `"command": "C:\\Users\\<用户名>\\.local\\bin\\wechat-mcp.exe"`）。

```json
{
  "mcpServers": {
    "wechat": {
      "command": "wechat-mcp",
      "description": "绿泡泡聊天记录与群聊检索 MCP"
    },
    "dingtalk": {
      "command": "dingtalk-mcp",
      "description": "DuangDuang聊天记录、群聊与通讯录检索 MCP"
    }
  }
}
```

### 方案 C：本地源码 / 指定虚拟环境运行

> **注意**：如果是在特定的 Python 虚拟环境中，可将 `"command"` 设为对应环境的 Python 路径，`args` 设为 `["-m", "wechat_mcp.server"]`。本地源码调试时可追加 `"env": { "PYTHONPATH": "<源码绝对路径>/src" }`。

---

## 🗑️ 彻底卸载与依赖清理指南 (Complete Uninstall & Teardown)

如果您不再需要使用 `im-mcp`，或者希望在公共机器上彻底清理所有导出的聊天数据、依赖包及客户端配置，请按照以下标准顺序进行完整清理：

### 第一步：退出 AI 客户端或结束常驻 MCP 服务进程 (Stop Running Services)

> 💡 **核心提示**：AI 客户端（如 WorkBuddy、Claude Desktop、Pi、Cursor 等）在调用过工具后，通常会保持 `wechat-mcp` 与 `dingtalk-mcp` 服务进程常驻。这些进程打开的 SQLite 句柄与 `-shm` / `-wal` 锁会导致底层数据文件无法直接被删除。

- **推荐做法**：直接**完全退出当前 AI 客户端**应用；
- **或通过终端结束服务进程**（Windows PowerShell）：
  ```powershell
  Get-Process | Where-Object { $_.ProcessName -match "wechat-mcp|dingtalk-mcp" } | Stop-Process -Force
  ```
- *注：内置清理工具 `im-clean` 也已提供进程占用自检与 `--force` 强制结束机制。*

### 第二步：清理导出的本地解密数据库与明文缓存 (Data Cleanup)

运行内置的 `im-clean` 命令，或直接手动删除对应的全局数据目录：

```bash
# 方式 A：使用内置命令清理（自带进程占用检测，推荐）
im-clean -y

# 若遇到残留进程句柄拒绝删除，可追加 --force 强制结束进程并强力清除
im-clean -y --force

# 方式 B：手动删除用户家目录下的数据文件夹
# Windows (PowerShell):
Remove-Item -Recurse -Force ~/.wechat_mcp, ~/.dingtalk_mcp
# Linux / macOS:
rm -rf ~/.wechat_mcp ~/.dingtalk_mcp
```

### 第三步：卸载 CLI 工具与 Python 依赖环境 (Environment Teardown)

根据最初采用的安装方式，执行对应的卸载命令：

1. **若使用了 `uv tool install`（全局持久化安装）**：
   ```bash
   uv tool uninstall im-mcp
   ```
2. **若使用了 `uvx` 即席运行（临时缓存）**：
   ```bash
   # 清理 uv 缓存中的归档与虚拟环境缓存（释放磁盘空间）
   uv cache clean
   ```
3. **若使用了全局/环境 `pip install`**：
   ```bash
   pip uninstall im-mcp
   ```

### 第四步：清理各客户端的 MCP 配置文件与 Skill (Client Config Removal)

> ⚠️ **注意**：由于各 AI 客户端（WorkBuddy、Pi、Claude Desktop、Cursor、Cline、Cherry Studio 等）采用本地配置文件管理 MCP，程序无法跨权限修改其他软件的私有配置，**这一步需用户根据自己的客户端环境手动操作**（常见客户端配置路径与清理方法详见 [`skills/im-mcp/SKILL.md`](skills/im-mcp/SKILL.md) 附录参考目录）。

---

## 📂 项目结构

```text
├── src/
│   ├── wechat_mcp/       # 绿泡泡 MCP 核心模块
│   │   ├── config.py
│   │   ├── parser.py
│   │   ├── database.py
│   │   ├── images.py     # 聊天图片解密（XOR / V1 固定密钥 / V2 账号级密钥）
│   │   ├── emoticons.py  # 自定义表情明文库（调用 wxemo 解密 + 按需 wxgf 转码）
│   │   ├── server.py     # 绿泡泡 MCP 服务 (wechat-mcp)
│   │   └── tools/        # 绿泡泡一键提取与解密 CLI (wechat-init)
│   │       └── key_tool.py   # 密钥提取（DBKey / passphrase / 图片 V2 密钥）
│   └── dingtalk_mcp/     # DuangDuang MCP 核心模块
│       ├── decrypt.py    # V2/V3 AES-ECB + WAL 解密
│       ├── db.py         # 128分表聚合查询与联系人实名映射
│       ├── server.py     # DuangDuang MCP 服务 (dingtalk-mcp)
│       └── tools/        # DuangDuang一键同步 CLI (dingtalk-init)
├── pyproject.toml        # 标准打包与 optional-dependencies 定义
├── README.md             # 架构与接入文档
└── skills/               # 配套 Agent Skill 指南
    └── im-mcp/
        └── SKILL.md      # 智能体自动化初始化与清理技能规范
```

---

## 🔗 友情链接 (Friendly Links)

- [LINUX DO](https://linux.do/) - 真诚、友善、团结、专业，共建自由开放的技术社区。