WeChat Local Agent MCP

A local-first, stdio-only MCP for letting an Agent search and summarize the computer owner's own WeChat history. It provides stable day/range pagination, bulk chat workflows, unread/event queries, context, structured message details, and explicitly gated OCR/file/voice/link enrichment.

This is an independent community project. It is not affiliated with or endorsed by Tencent or WeChat. Use it only for data you own or are authorized to access, subject to local law and applicable terms.

Give this repository to an Agent

Tell an installation-capable Agent:

Clone https://github.com/hetiankong/wechat-local-agent-mcp, read AGENTS.md in
full, and follow it to install and verify the local read-only WeChat MCP.
Do not expose keys or message contents during setup.

AGENTS.md is the complete platform decision tree, safety contract, install runbook, verification checklist, troubleshooting guide, and large-chat recipe.

For a manual macOS Apple Silicon install:

git clone https://github.com/hetiankong/wechat-local-agent-mcp.git
cd wechat-local-agent-mcp
./scripts/install.sh --register-codex
./scripts/bootstrap-macos.sh

For Windows 11 amd64 PowerShell:

git clone https://github.com/hetiankong/wechat-local-agent-mcp.git
cd wechat-local-agent-mcp
.\scripts\install.ps1 -RegisterCodex

The installer downloads an official r266-tech/wechat-cli release and fails closed unless its .sha256 sidecar verifies. No WeChat databases, keys, decoded media, messages, or account identifiers are included in this repository. An offline pair can be supplied through WECHAT_CLI_RELEASE_ZIP and WECHAT_CLI_RELEASE_SHA256 without weakening checksum verification.

Related MCP server: wx4py-mcp

Product workflows

Core tools include:

• resolve_chat, sessions, search, timeline

• read_chat_day, read_chat_range, read_multiple_chats_day

• count_messages, unread, read_events, group_members

• context, message_details

Optional tools include message_media, ocr_message_images, extract_message_files, transcribe_message_voice, and fetch_message_links. Each is independently gated by environment variables; ordinary reads never expose media paths or debug/key fields.

Read 900 messages from one day

Ask the Agent:

读取“项目群”今天的全部消息。先 resolve_chat 和 count_messages，再循环
read_chat_day(limit=200)，每次使用 next_cursor，直到 done=true。逐页总结后按
时间顺序合并，重要结论保留消息 ID、发送者和时间。

This takes about five bounded MCP calls, avoids offset drift, and keeps the summary traceable. period accepts today/今天, yesterday/昨天, this_week/本周, last_week/上周, recent-hour forms, or any YYYY-MM-DD.

Security boundary

• Core subprocess calls use argv arrays, shell=False, closed stdin, timeouts, bounded output, an allowlist, and strict read-only mode.

• The MCP has no generic SQL/command execution, export, send/reply, UI control, or indefinite watcher.

• macOS setup keeps SIP enabled and uses a managed shadow app rather than re-signing the installed WeChat app.

• The reviewed wxkey patch never receives or stores an administrator password; macOS Authorization Services owns the prompt.

• Network link fetching is disabled by default and blocks credentials, private IPs, unsafe redirects, non-text content, and oversized responses.

See SECURITY.md for reporting and data-handling details.

Development

python3 -m venv .venv
.venv/bin/python -m pip install -e . pytest
.venv/bin/python -m pytest -q

The Python unit/security suite does not require WeChat data. Live acceptance must emit only counts, booleans, and field names—not user data.

Acknowledgements

The query runtime and key bootstrap build on the work of r266-tech/wechat-cli and r266-tech/wxkey. The architecture was also informed by the local-data work of labazhou2024/chatlog-keeper, Thearas/wechat-db-decrypt-macos, tomqiaozc/wx-dump-mac, cocohahaha/wechat-decrypt-macos, and ylytdeng/wechat-decrypt.

Licenses and exact usage are documented in THIRD_PARTY_NOTICES.md.