Skip to main content
Glama
wechat-mcp-server

wechat-mcp-server

by 1335907208

wechat-mcp-server

一个用于读取本机微信数据的 MCP Server:让 Claude Code 等 AI 助手可以通过 MCP 工具读取聊天记录/会话/联系人/收藏等。

功能特性

  • 查询微信聊天记录、联系人、会话列表、收藏等

  • Skill 蒸馏:从聊天记录提取个人沟通风格(统计 + Few-shot + 可生成系统提示词)

  • 消息监听:近实时获取新消息(轮询会话数据库)

  • 表情包管理:解析表情消息、构建表情包库,并支持解析 [sticker:xxx] 占位符

Related MCP server: WeChat Local Agent MCP

安装

# 克隆并安装
git clone <repo-url>
cd wechat-mcp-server
pip install -e .

初始化(首次必做)

首次使用需要提取微信数据库解密密钥(会写入到 ~/.wechat-cli/all_keys.json):

wechat-cli-mcp init

你也可以手动指定微信数据目录(db_storage):

wechat-cli-mcp init --db-dir "D:\\...\\db_storage"

重要提示(务必看)

  • 初始化时必须保证微信正在运行(Windows 为 Weixin.exe),否则无法从进程内存提取密钥。

  • 权限问题:部分系统/环境下可能需要管理员权限运行终端。

  • 只读原则:本项目只读取/解析数据,不包含“发送消息”能力。

  • 密钥文件位置:默认使用 ~/.wechat-cli/all_keys.json。删除该文件后需要重新执行 init。

启动 MCP Server

你有 3 种方式启动(任选其一):

方式一:安装后直接启动(推荐)

安装 pip install -e . 后,会安装命令行入口:

wechat-cli-mcp

Windows 下推荐使用 SSE 模式(更稳定):

wechat-cli-mcp --sse

或通过环境变量:

MCP_TRANSPORT=sse wechat-cli-mcp

启动后会显示:

INFO:     Uvicorn running on http://127.0.0.1:8000

方式二:配置到 Claude Code

在你的 .mcp.json 添加:

{
  "mcpServers": {
    "wechat-cli-mcp": {
      "type": "stdio",
      "command": "wechat-cli-mcp"
    }
  }
}

Windows 下推荐使用 SSE 配置:

{
  "mcpServers": {
    "wechat-cli-mcp": {
      "type": "sse",
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}

或使用 Claude CLI:

claude mcp add wechat-cli-mcp -- wechat-cli-mcp

注意:如果使用 SSE 模式,需要先手动启动 server(方式一),然后再配置 IDE 连接。

方式三:用 Python 模块启动

python -m wechat_cli_mcp

Windows 下加 SSE 参数:

python -m wechat_cli_mcp --sse

工具列表(MCP Tools)

基础查询工具

工具

说明

wechat_sessions

列出最近聊天会话

wechat_history

读取指定会话的聊天记录

wechat_search

按关键词搜索消息

wechat_contacts

搜索联系人

wechat_unread

未读会话

wechat_new_messages

增量获取新消息(自上次检查之后)

wechat_members

群成员列表

wechat_stats

会话统计

wechat_favorites

收藏/书签

Skill 蒸馏工具

工具

说明

wechat_distill_skill

从聊天记录蒸馏个人沟通风格(返回 JSON 或 Markdown)

wechat_save_skill

蒸馏并保存到文件(JSON 或 Markdown)

示例:

# 从多个会话蒸馏
wechat_distill_skill(chat_names="张三,李四,工作群", message_limit=500)

# 保存为 Markdown
wechat_save_skill(chat_names="张三", output_path="my_style.md", output_format="markdown")

消息监听工具

工具

说明

wechat_start_listener

启动监听(近实时)

wechat_stop_listener

停止监听

wechat_listener_status

查看监听状态

wechat_get_buffered_messages

获取监听缓冲的新消息

说明:监听器会轮询会话数据库的最新时间戳来发现新消息,并将新消息缓冲到内存中供工具读取。

示例:

wechat_start_listener(interval=0.5)
wechat_listener_status()
wechat_get_buffered_messages(clear=true)
wechat_stop_listener()

表情包工具

工具

说明

wechat_build_sticker_library

从聊天记录中提取表情包,生成表情包统计/列表

wechat_search_stickers

在表情包库中搜索

wechat_list_stickers

列出表情包库全部内容

wechat_add_sticker

手动添加表情到库(命名,用于占位符)

wechat_parse_sticker_placeholder

解析文本里的 [sticker:xxx] 占位符

示例:

wechat_build_sticker_library(chat_name="张三", limit=500)
wechat_search_stickers(query="搞笑", limit=10)
wechat_parse_sticker_placeholder(text="哈哈 [sticker:狗头]")

实时消息监听 CLI 工具

项目包含一个独立的命令行工具 wechat-listen,可以实时监听并显示微信新消息。

使用方法

自动检测消息目录:

wechat-listen

指定消息目录:

wechat-listen --msg-dir "D:\xwechat_files\wxid_xxx\db_storage\message"

设置轮询间隔:

wechat-listen --interval 0.3

功能说明

  • 进入交互模式后,实时显示新收到的消息

  • 显示发送者、会话、消息内容和时间

  • 按 Ctrl+C 退出监听

  • 适合用于实时监控微信消息

示例输出

启动监听器...
监听器已启动,监控: D:\xwechat_files\wxid_xxx\db_storage\message
按 Ctrl+C 退出
==================================================

[16:30:15] [群] 工作群
  张三: 大家好

[16:31:02] 李四
  李四: 收到

常见使用场景

场景 1:把你的聊天风格“蒸馏”成系统提示词

  • 对多个你常用的会话做 wechat_distill_skill

  • 将输出的 system_prompt 放到你使用的任意 LLM/Agent 的 system prompt 中

场景 2:自动回复(需要你自己实现“发送”)

本项目只负责读数据 / 监听 / 风格蒸馏。

你可以组合:

  • wechat_start_listener 获取新消息

  • LLM 根据蒸馏后的风格生成回复(可带 [sticker:xxx])

  • 再用 UI 自动化/其他方式去“发送”(发送不在本项目范围内)

License

MIT

Available Tools

20 tools
wechat_add_stickerB

Add a sticker to the library.

Args: name: Name for the sticker (used in [sticker:name] placeholders) md5: MD5 hash of the sticker file_path: Path to the sticker file description: Description of the sticker tags: Comma-separated tags for searching

Returns: Status message

Inputs: md5 (required), name (required), file_path (required), tags, +1 more. Returns: result

wechat_build_sticker_libraryA

Build sticker library from chat history.

Extracts sticker information including MD5, type, usage count.

Args: chat_name: Chat name to analyze limit: Maximum messages to scan copy_files: Whether to copy sticker files to output_dir output_dir: Directory to copy sticker files (if copy_files=True)

Returns: JSON with sticker library and usage patterns

Inputs: chat_name (required), limit, copy_files, output_dir. Returns: result

wechat_contactsC

Search WeChat contacts

Inputs: query, detail. Returns: result

wechat_distill_skillA

Distill personal communication style from chat history into an Agent Skills compliant SKILL.md.

Args: chat_names: Comma-separated list of chat names to analyze message_limit: Maximum messages to analyze per chat output_format: 'markdown' (Agent Skills SKILL.md) or 'json'

Returns: Agent Skills compliant skill data with YAML frontmatter, style rules, and few-shot examples

Inputs: chat_names (required), message_limit, output_format. Returns: result

wechat_favoritesC

List WeChat favorites/bookmarks

Inputs: query, msg_type. Returns: result

wechat_get_buffered_messagesA

Get buffered messages from the listener.

Args: clear: Whether to clear the buffer after reading (default True)

Returns: JSON array of buffered messages

Inputs: clear. Returns: result

wechat_historyB

Read chat history from a specific WeChat conversation

Inputs: chat_name (required), limit, msg_type. Returns: result

wechat_listener_statusA

Get the current status of the message listener.

Returns: Listener state and statistics

Inputs: no named parameters. Returns: result

wechat_list_stickersA

List all stickers in the library.

Returns: JSON object with all stickers

Inputs: no named parameters. Returns: result

wechat_membersC

List members of a WeChat group

Inputs: group_name (required). Returns: result

wechat_new_messagesA

Get new WeChat messages since last check (incremental)

Inputs: no named parameters. Returns: result

wechat_parse_sticker_placeholderA

Parse sticker placeholders from text.

Example: "Hello [sticker:dog]" -> [{"type": "text", "content": "Hello "}, {"type": "sticker", "name": "dog"}]

Args: text: Text with sticker placeholders

Returns: JSON array of parsed parts

Inputs: text (required). Returns: result

wechat_save_skillA

Distill and save skill to file as Agent Skills compliant SKILL.md.

Args: chat_names: Comma-separated list of chat names output_path: Path to save the skill file (will create SKILL.md per Agent Skills spec) message_limit: Maximum messages per chat output_format: 'markdown' (Agent Skills SKILL.md) or 'json'

Returns: Path to saved SKILL.md file or error message

Inputs: chat_names (required), output_path (required), message_limit, output_format. Returns: result

wechat_search_stickersB

Search sticker library by name or description.

Args: query: Search query limit: Maximum results to return

Returns: JSON array of matching stickers

Inputs: query (required), limit. Returns: result

wechat_sessionsC

List recent WeChat chat sessions/conversations

Inputs: limit. Returns: result

wechat_start_listenerA

Start listening for new WeChat messages.

The listener monitors database changes and buffers new messages. Use wechat_get_buffered_messages to retrieve them.

Args: msg_dir: WeChat message directory path (e.g., "D:\xwechat_files\wxid_xxx\msg"). If not provided, will auto-detect. interval: Polling interval in seconds (default 0.5)

Returns: Status message

Inputs: msg_dir, interval. Returns: result

wechat_statsC

Get statistics for a WeChat chat

Inputs: chat_name (required), end_time, start_time. Returns: result

wechat_stop_listenerA

Stop the message listener.

Returns: Status message

Inputs: no named parameters. Returns: result

wechat_unreadC

Show unread WeChat sessions

Inputs: limit. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 20 tools

    Disambiguation4/5

    Tools have mostly distinct purposes, with slight overlap between message retrieval tools (history, new_messages, get_buffered_messages) but descriptions clarify differences. Sticker and skill tools are well-separated.

    Naming Consistency3/5

    All tools start with 'wechat_', but some follow verb_noun pattern (wechat_add_sticker) while others are noun-only (wechat_contacts, wechat_history), causing minor inconsistency.

    Tool Count5/5

    20 tools is appropriate for a WeChat integration, covering contacts, sessions, messages, stickers, skills, and listener functionality without being overwhelming.

    Completeness2/5

    Missing core functionality like sending messages or modifying contacts, which are expected for a chat server. Focus is on data retrieval and analysis, leaving significant gaps.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server providing an Agent-first, read-only interface to authorized WeChat conversations, with CLI and plugin support for Codex and Claude Code.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to query local WeChat chat data through read-only MCP tools, including sessions, messages, contacts, search, and statistics, with everything processed locally.
      63 PyPI
      6
      MIT