wechat-reader-mcp
Provides access to local WeChat desktop messages, including connection status, recent sessions with unread counts, chat history, contact and group search, and live monitoring of specified chats. An optional send tool can be enabled to send messages through a visible WeChat desktop client.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
wechat-reader-mcp
A self-contained, read-first MCP (Model Context Protocol) server that exposes your local WeChat desktop messages to any MCP-capable AI client (ZCode, Claude Desktop, Cursor, Cherry Studio, ...). One click to install, one command to register — the AI does the rest.
中文文档:README_cn.md
Real data, not screenshots — messages are read by decrypting the local WeChat database (SQLCipher). The key is obtained by a read-only memory scan of the running WeChat process: no DLL injection, no process modification, no network-protocol interference.
Read-only by default — 7 reading tools; the optional
wechat_sendtool is not even registered unless you explicitly enable it in config.Local only — everything runs on your machine. Data leaves your machine only through the AI client you connect (see Privacy & responsible use).
How it works
WeChat desktop (Weixin.exe, 4.1.12+ / tested 4.1.15.56)
│ local encrypted SQLite (SQLCipher4) in xwechat_files/
│ key: read-only memory scan of the logged-in process
▼
wechat_reader_mcp/wx_client.py (adapter: sessions / history / live listener / send)
▼
wechat_reader_mcp/server.py (MCP server, official MCP Python SDK, stdio or SSE)
▼
Any MCP client ──► AI calls tools: wechat_status / wechat_read / ...Related MCP server: wechat-mcp
Requirements
OS | Windows 10/11 |
Python | 3.10 – 3.12 on PATH (or the |
Desktop client 4.1.12+, logged in while reading (the key lives in the process memory) | |
Network | Only for |
Quick start (one click)
double-click install.batinstall.bat is idempotent. It will:
create
.venv\and install dependencies (wechatauto-replica,mcp),add a tkinter stub if your base Python lacks tcl/tk,
auto-register the server into every AI client it detects (see table below),
run an end-to-end self-test (MCP handshake → tool list → connect WeChat → read).
Then restart your AI client / open a new session — done.
Manual / headless equivalent
python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
.venv\Scripts\python.exe register_mcp.py
.venv\Scripts\python.exe test_client.pyAI-native usage
This project is designed to be operated by AI agents, not just humans.
AGENTS.mdis the machine-facing entry point: task-oriented commands, conventions, and rules for any agent that opens this folder.install.batwrites an.agents/mcp.jsoninto this folder, so agents that support workspace-scope MCP auto-connect the moment they open this directory.Deterministic verification:
test_client.pyexits0/1and prints a checklist — an agent can self-verify without human judgement.
Tell your AI agent, e.g.:
Run
wechat-reader-mcp\install.bat, then verify withwechat_statusand summarize my 5 most recent sessions viawechat_sessions.
Listen to the chat "Alice" (
wechat_listen_add) and pollwechat_listen_poll(wait_seconds=20)until she replies, then summarize the conversation.
MCP tools (7 read-only + optional send)
Tool | Description |
| Connection state, WeChat client version, my account, listeners, buffered new-message count. First call connects (key scan takes a few seconds; WeChat must be logged in). |
| Recent chat list with unread counts; with |
| Read chat history, ascending by time; increase |
| Search contacts & groups; returned |
| Start live monitoring of a chat (persisted; restored on restart). |
| Fetch buffered new messages; may block waiting (e.g. |
| Stop monitoring a chat. |
| Only exists if |
Typical AI flow: wechat_status → wechat_sessions → wechat_read →
wechat_listen_add + wechat_listen_poll(wait_seconds=20).
Where it registers
register_mcp.py (idempotent, safe-merging; --remove undoes everything):
Target | Config file | Shape |
ZCode (user scope, all workspaces) |
|
|
Claude Desktop |
|
|
Cursor |
|
|
This folder (agents opening it auto-connect) |
|
|
Clients not on this list: use command = <project>\.venv\Scripts\python.exe,
args = ["<project>\wechat_reader_mcp\server.py"]. For URL-based clients run
run_sse.bat → http://127.0.0.1:8790/sse.
Configuration
wechat_reader_mcp\config.json — generated on first run; all keys optional.
Key | Default | Meaning |
|
|
|
|
| Chats auto-restored at startup (written by |
|
| Max blocking seconds for |
Lifecycle
Action | Command |
Install / repair / update dependencies | re-run |
Register / refresh after moving the folder |
|
Verify |
|
Deregister + remove venv |
|
Remove everything |
|
Configs store absolute paths — after moving the project, re-run register_mcp.py.
Troubleshooting
Symptom | Fix |
"连接微信数据库失败" / connect error | WeChat desktop is not running or not logged in. Log in, retry — no restart needed. |
"未找到会话「xx」" | The name must exactly match the remark/nickname in WeChat. Call |
tkinter ImportError | Base Python lacks tcl/tk; |
pip slow / fails | Mirror is preconfigured; alternatively |
Reading broke after a WeChat upgrade | A major WeChat version change can break DB/key compatibility. Pin/upgrade |
Privacy & responsible use
This is not an official WeChat integration. WeChat ships no personal-account API; local database encryption is an intentional boundary set by Tencent. This tool decrypts your own data on your own machine. Strictly speaking it violates the WeChat ToS; the read path is purely local (no injection, no protocol tampering) and practically invisible to the server side, while the send path (off by default) is server-visible and is where account bans actually concentrate. If you enable it, keep it low-frequency and human-like.
The MCP server keeps data on your machine. Whatever the connected AI client does with the content it reads (e.g. uploading context to a cloud model) is that client's behavior — connect only clients you trust.
This tool is a master key to all your chat history: anyone with access to your logged-in machine can read everything. Lock your machine.
Use for personal purposes only. Do not redistribute or resell anyone's chat data.
Project layout
wechat-reader-mcp/
├── install.bat one-click: venv → deps → stub → register → self-test (idempotent)
├── uninstall.bat deregister + remove .venv
├── register_mcp.py register/remove server config in AI clients (--remove, --target, --name)
├── test_client.py end-to-end self-test (exit code 0/1)
├── prepare_stub.py tkinter stub for tcl/tk-less Pythons (auto-invoked)
├── run_sse.bat optional SSE mode on http://127.0.0.1:8790/sse
├── requirements.txt wechatauto-replica + mcp
├── README.md / README_cn.md / AGENTS.md / LICENSE
└── wechat_reader_mcp/
├── server.py MCP server (7 read-only tools + optional send)
├── wx_client.py WeChat adapter (DB decrypt read, listener, UIA send)
└── config.json runtime config (generated, gitignored)License
MIT. Underlying libraries: wechatauto-replica and the MCP Python SDK (both MIT).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Hosted WhatsApp MCP server: read, search and reply to your own WhatsApp chats from your AI.
Your own WhatsApp as an MCP server: read, search and send from any MCP client.
Drive WhatsApp from any MCP client: pair devices, send text and media, manage contacts and groups.
Free WhatsApp MCP server for ChatGPT and Claude: read and search chats, every send you approve.
Related MCP Servers
- FlicenseCqualityDmaintenanceMCP server for reading local WeChat data, enabling AI assistants to query chat history, contacts, sessions, and more via MCP tools.209-
- FlicenseNot gradedqualityDmaintenanceEnables MCP clients to control the Windows WeChat desktop app, including reading conversations, sending messages, searching contacts, and monitoring new messages via UI automation.-
- AlicenseNot gradedqualityBmaintenanceAn unofficial experimental local MCP server that lets AI clients work with an already logged-in Windows Weixin desktop client, providing bounded conversation and message reads, group and message search, polling of up to 16 selected chats, guarded text and attachment submission, and image/file viewing handoffs. It also exposes hybrid Computer Use prompts for native mention handoffs, while remeasuring the window, DPI, and target controls on each action and failing closed when evidence is insufficient.1Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients on Windows to read WeChat sessions, contacts, messages, media, and files through WeFlow, and to send or natively forward messages via the desktop WeChat client.MIT