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

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

💡 复制即用提示词（直接发给你的 AI Agent / 客户端）：

请阅读并遵循开源项目 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)

🧰 提供的 MCP Tools

1. 绿泡泡 (wechat-mcp)

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

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

消息检索

会话与通讯录

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

分析与同步

2. DuangDuang (dingtalk-mcp)

📦 安装与运行方式

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

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

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

# 全局安装 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]）：

# 直接免安装即席运行初始化
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 安装（支持按需依赖）

# 两个平台都需要（全量）
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 中完整定义了面向各平台 AI Agent（Pi、Claude Desktop/Code、Cursor、Cline 等）的完整自动化运维规范（涵盖依赖运行策略、初始化前置检查、MCP 工具链调用 SOP、异常处置禁令及附录参考目录）。

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

• 通用智能体环境 (Pi / Codex / Pebrel)：

  mkdir -p ~/.agents/skills/im-mcp && cp skills/im-mcp/SKILL.md ~/.agents/skills/im-mcp/
  

• Claude Code / Desktop：

  mkdir -p ~/.claude/skills/im-mcp && cp skills/im-mcp/SKILL.md ~/.claude/skills/im-mcp/
  

• 当前项目工作区本地生效：

  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 派生与全库零依赖极速解密。

# 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，普通用户终端即可执行：

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

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

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

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

# 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 中显式固化全局数据目录，杜绝工作目录变动影响：

{
  "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"）。

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

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

注意：如果是在特定的 Python 虚拟环境中，可将 "command" 设为对应环境的 Python 路径，args 设为 `["-m", "wechat_mcp.s