Content
wechat-local-mcp
A read-only, local MCP service that converts your macOS WeChat conversations into searchable and extractable to-do context.
It consists of two layers:
1. A one-time preparation layer: captures the 32-byte key for each database from the local WeChat account directory and decrypts the database into independent snapshots.
2. An MCP query layer: only reads snapshots, send messages to WeChat modify the WeChat database does not require internet access.
WeChat is upgraded the preparation layer needs to be like `wechat_list_chats`, `wechat_search_messages`, and `wechat_find_t do not need to be rewritten.
and Version Compatibility
`wechat_status` dynamically reads the current WeChat version. Chat databases are usually located at:
`~/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/<account>/db_storage/`
Newer macOS WeChat versions may use separate keys for each database, and older tools that use a single key for all databases may not work directly. The database structure or key derivation method may change after a. The tool does notApplications/WeChat.app` the daily We.
## Security and Privacy
repository does not contain real keysChat databases, chat exports, account directories, or local virtual environments.
- The MCP service itself does not access and only reads local decrypted- When the MCP client passes query results to the model for analysis selected chat content will enter the context; please judge whether to use it according to the client's privacy policy.
- The key capture script should only be used for local WeChat accounts that you have the right to access.
- `keys.json` and plaintext snapshots are saved in the user configuration directory outside the project directory by default and are restricted to read-only for the current system account; do not submit or share them.
## Installation
Run the following command in this directory:
```bash
uv sync --extra keys --extra ui --extra test --python /opt/homebrew/bin/python3.12
the status:
```bash run --python /opt/homebrew/bin/python3.12 wechat status
```
## One Preparation
If you already have a usable `keys.json`, place it`~/.config/wechat-local-mcp/keys.json`
is a mapping of database relative paths file names) to 64-bit hexadecimal keys, for examplejson
{
"contact/contact.db": "REPLACE_WITH_HEX_CHARACTERS",
/message_0.db": "REPLACE_WITH_64_HEX_CHARACTERS"
}
```
If you don't have a `keys.json` file, the project comes with a Frida auxiliary script that does not modify the daily WeChat installation package. First, install the optional dependencies:
```bash
uv sync --extra keys --python /opt/homebrew/bin/python3.12
```
Directly attaching to the daily WeChat on some macOS versions may be rejected by the system. If the local machine allows attachment, exit and reopen WeChat, then run:
```bash
uv run --python /opt/homebrew/bin/python3.12 python scripts/capture_keys.py \
--pid "$(pgrep -x WeChat | head -1)" \
--db-dir "$HOME/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwe/<account>/db_storage"
```
This only merges the captured into `~/.config-local-mcp/keys.json not clear previously captured. If macOS reports `` or permission errors, use the dedicated copy:
```bashsh scripts/prepare_capture
```
Exit the daily We run the capture script with `--spawn "$HOME/Applications/Capture.app/Contents/MacOS/WeChat"`. installs a read-only derived function observer when WeChat starts; the current version usually does not require re-scanning the QR code. The script does not modify system settings and does daily `/Applications/.app`.
> Key capture is a one-time environmental preparation, and WeChat version or next require redoing. Do notkeys.json`, plaintext databases chat export files to Git.
rypting Local Snapshots is recommended to completely exit We running:
```bash
uv run --python /opt/homebrew/bin/python3.12 wechat-local-sync sync
```
The default output is:
`~/Library/Application Support/wechat-local-vault/decrypted/current/`
You can also override it with environment variables:
```bash
export WECHAT_CONTAINER_DIR="$HOME/Library/Containers/com.tencent.xinWeChat/Data/Documents"
export WECHAT_DECRYPTED_DIR="$HOME/Library/Application Support/wechat-local-vault/decrypted/current"
export WECHAT_KEYS_FILE="$HOME/.config/wechat-local-mcp/keys.json"
```
## Configuring MCP
Add it to the MCP client in stdio mode:
```json
{
"mcpServers": {
"wechat-local": {
"command": "/absolute/path/outputs/wechat-local-mcp/.venv/bin/wechat-local-mcp",
"args": ["--transport", "stdio"]
}
}
}
```
Or run it directly:
```bash
uv run --python /opt/homebrew/bin/python3.12 wechat-local-mcp --transport stdio
```
Codex CLI can register directly:
```bash
codex mcp add wechat-local -- \
"/absolute/path/outputs/wechat-local-mcp/.venv/bin/wechat-local-mcp" \
--transport stdio
```
## Available Tools
- `wechat_status`: checks WeChat version, database, key, and snapshot status.
- `wechat_sync`: decrypts databases to independent snapshot directories based on `keys.json`.
- `wechat_list_chats`: lists contacts and group chats, supports pagination.
- `wechat_read_chat`: reads messages by nickname, remark, group name, or WeChat ID.
- `wechat_search_messages`: searches messages by keyword, chat, and time range.
- `wechat_recent_messages`: summarizes recent messages.
- `wechat_find_todos`: uses interpretable Chinese and English action items to heuristically find to-do candidates.
- `wechat_chat_summary`: returns participant statistics and to-do candidates for further summarization by the model.
- `wechat_ui_diagnose`: diagnoses screen recording/OCR read-only fallback.
- `wechat_list_recent_chats`: reads visible conversations in the current window when the database snapshot is not available.
- `wechat_read_chat_ui`: reads chats using local OCR when the database snapshot is not available.
- `wechat_find_todos_ui`: extracts to-do candidates from OCR results.
All query tools are read-only; `wechat_find_todos` only returns candidates and does not create tasks, send messages, or modify WeChat.
OCR fallback requires:
```bash
uv sync --extra ui --python /opt/homebrew/bin/python3.12
```
And allows the terminal running MCP to use "Screen and System Audio Recording" in system settings. OCR is an approximate read of the current screen, and long-term history, precise sender, and full-text search still rely on the database snapshot backend.
## Verification
```bash
uv run --python /opt/homebrew/bin/python3.12 pytest
uv run --python /opt/homebrew/bin/python3.12 wechat-local-sync status
```
If there is no plaintext snapshot, MCP will return a hint for the next step and will not mistakenly treat the encrypted database as readable content.
## License and Statement
This project is licensed under the [MIT License](LICENSE).
This project is a community-developed, unofficial tool and has no affiliation or endorsement from Tencent or the WeChat team. "WeChat" and "WeChat" and related logos belong to their respective rights holders.
