WeChat MCP 服务器

使用说明（Markdown 格式）

• 项目简介

  • 该仓库实现了一个 MCP 服务器，用于向 LLM 客户端提供微信数据的上下文信息和功能入口。服务器通过 Claude Code 等工具集成，可以读取最近会话、指定聊天历史、全库搜索、获取联系人，以及获取自上次调用以来的新消息等能力，并提供对微信图片的解密支持。

• 主要功能点

  • MCP 服务器核心：实现基于 MCP 的工具注册与调用，提供按需向客户端返回结构化信息。
  • 数据查询工具（5 种常用工具）：get_recent_sessions, get_chat_history, search_messages, get_contacts, get_new_messages，用于获取会话、历史记录、全文检索、联系人与新消息等。
  • 附加能力：decode_image 与图片相关解密/渲染能力，方便将微信图片在 LLM 场景中呈现。
  • 数据源与解密：服务器侧通过 keys 文件和 decrypted 数据目录对本地微信数据库进行解密查询与数据访问，结合 WAL 与页面解密逻辑提供稳定的数据视图。
  • 客户端集成：可通过 Claude Code 等 MCP 客户端直接配置并调用服务器暴露的工具。

• 安装步骤

  • 先决条件：安装 Python 3.x，确保微信正在运行且本地数据可访问。
  • 安装依赖库（示例性依赖，实际以项目需要为准）：
    • pip install mcp pycryptodome zstandard
  • 配置准备：
    • 需要一个 config.json（仓库已有配置加载逻辑）来指向微信数据库根目录、解密密钥等信息。
    • 通过 find_all_keys.py 提取密钥并生成 all_keys.json，确保服务器能够解密数据库。
  • 启动服务：
    • 直接运行 mcp_server.py（在仓库根目录下执行：python mcp_server.py 即可启动 MCP 服务端）。

• 服务器配置（给 MCP 客户端使用的启动信息，json 形式）

  • server name: wechat
  • command: python
  • args: ["mcp_server.py"] 注释：该配置用于 MCP 客户端启动并连接到后端服务器。MCP 客户端（如 Claude Code）需要提供 serverName、command、args 以启动服务器进程并建立 RPC 通道。客户端本身不需要实现服务器代码，仅用于调用此服务。

• 基本使用方法

  • 在 MCP 客户端中配置服务器，指定名称为 wechat，命令为 python，参数为 mcp_server.py。
  • 启动服务器后，使用客户端调用下列工具：
    • get_recent_sessions(limit)
    • get_chat_history(chat_name, limit)
    • search_messages(keyword, limit)
    • get_contacts(query, limit)
    • get_new_messages()
  • 如需查看/获取图片等辅助内容，可以结合 decode_image 等功能进行图片解密与渲染。
  • 具体调用格式请参考 MCP 客户端对 JSON-RPC 请求和响应的规范。

• 运行与调试要点

  • 确保微信进程可被访问，以便密钥及数据解密能够工作。
  • 配置中的路径（db_dir、decrypted_dir、keys_file 等）要与实际环境匹配。
  • 运行时如遇权限问题，请以管理员身份执行。