GreenBubbles for Windows MCP Server
Provides read-only access to locally stored WeChat 4.x chat history, enabling agents to list conversations, retrieve messages for contacts or groups within time ranges, search messages, fetch individual messages and attachment metadata, and check source status via CLI, HTTP, or MCP.
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.
GreenBubbles for Windows reads the databases WeChat 4.x already keeps on your PC.
It never changes WeChat's files and never keeps an exported chat database in sync.
Point it at a contact or group and a time window; it decrypts only what is needed
and returns greenbubbles.query.v1 JSON.
Beta. Windows 10/11 x64, WeChat 4.x. The portable ZIP ships with Python 3.12; end users do not need Python, pip or Visual Studio.
What you can do
Browse and search: list conversations, read messages, search locally, and open attachments.
Give an agent a narrow window: query one contact or group for a time range over HTTP or MCP.
Archive: export Markdown, JSONL and HTML with attachment files, incrementally.
Back up: create an encrypted snapshot unlocked by a 24-word recovery phrase.
Stay offline: keys, decryption, search and archives stay on this machine.
Related MCP server: wechat-local-reader
Install
Download
greenbubbles-win-<version>-portable.zipfrom Releases.Unzip it anywhere.
Sign in to WeChat and keep it running.
Check access:
.\greenbubbles.cmd source statusThe first run captures the database key from your own running Weixin.exe.
The key is saved under state\, which is gitignored and never uploaded.
Usage
I want to... | Command |
List recent chats |
|
Find a chat by name |
|
Read one chat and time range |
|
Search message text |
|
Fetch one message |
|
Include attachment metadata | add |
Export with files |
|
Update an archive |
|
Use page.nextCursor from the previous page as --cursor.
Times accept YYYY-MM-DD, YYYY-MM-DD HH:MM, ISO timestamps or Unix seconds;
both ends are inclusive. Full command list: CLI contract.
Agent access
Start the loopback-only connector on the Windows PC:
.\start-connector-local.cmdIt binds 127.0.0.1:8787. On first start it writes a random bearer token to
state\token.txt; restarts reuse the same token. Delete that file and restart
the connector to rotate it.
Another machine? Use an SSH tunnel
The connector stays on loopback. The tunnel carries the port, not the token.
One-time setup on Windows, in an elevated PowerShell:
Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
Set-Service sshd -StartupType Automatic
Start-Service sshd
New-NetFirewallRule -DisplayName "OpenSSH 22" -Direction Inbound -Protocol TCP -LocalPort 22 -Action AllowConfirm both commands report the expected state:
Get-WindowsCapability -Online -Name OpenSSH.Server* # State: Installed
Get-Service sshd # Status: RunningIf the capability stays InstallPending (seen on some Home editions and
locked-down Windows Update machines), use the signed Win32-OpenSSH build
instead. See SERVICE.md for the verified install and
rollback steps.
From the caller machine, open the tunnel and copy the token once over a trusted channel:
ssh -N -L 8787:127.0.0.1:8787 <windows-user>@<windows-ip>
scp '<windows-user>@<windows-ip>:D:/path/to/greenbubbles-win/state/token.txt' ~/.greenbubbles-token
chmod 600 ~/.greenbubbles-tokenThen an agent calls:
curl -H "Authorization: Bearer $(cat ~/.greenbubbles-token)" \
"http://127.0.0.1:8787/api/v1/chats?limit=3"Treat the token like a password: never put it in prompts, commits or shared logs.
MCP is available over stdio with six tools:
list_conversations, get_messages, search_messages, list_contacts,
get_message, source_status.
Do not expose the port to the public internet. Interface details: INTERFACE.md · agent prompt: AGENT-PROMPT.md · background service: SERVICE.md.
Archive and snapshot
greenbubbles.cmd archive export --out .\archive --formats md,jsonl,html --attachments
greenbubbles.cmd snapshot create --out-dir .\archive --file history.gbvault
greenbubbles.cmd snapshot restore --file history.gbvault --mnemonic "..." --out-dir .\restoredarchive update is incremental and idempotent; export rewrites the whole set.
Snapshots use Argon2id + ChaCha20-Poly1305; the 24-word phrase is shown once.
The snapshot can be opened later without WeChat.
Privacy
Everything GreenBubbles reads or writes stays on this PC: WeChat's databases, the captured key, archives and snapshots. There is no telemetry or update check. When you connect a cloud agent, the messages that agent reads leave this PC through that agent, not through GreenBubbles.
The connector is read-only. It does not send messages, change WeChat files or
upload chat content. Treat state\keys.json, state\token.txt, archives and
snapshots as sensitive as WeChat itself.
Status and limitations
Windows 10/11 x64; WeChat 4.x (tested on 4.1.11.24).
WeChat must be signed in for the first key capture; later reads can use the saved key.
wxgfimages are HEVC containers; the connector validates the key and decode but does not transcode previews.No GUI; the interfaces are CLI, HTTP and MCP.
The portable ZIP is unsigned; SmartScreen may warn on first launch.
WeChat changes its private formats; when a format cannot be read, the tool reports it instead of guessing.
See known limitations and FAQ.
Documentation
I want to... | Read |
Use the CLI, HTTP API or MCP | |
Give another agent access | |
Run a background service | |
Understand the design | |
Review regression coverage | |
Read this page in Chinese |
All docs: docs/README.md.
Contributing
Issues and pull requests are welcome. Use synthetic examples in reports and tests; never include real messages, databases, keys or account paths. See CONTRIBUTING.md and SECURITY.md.
License
MIT. See LICENSE, NOTICE.md and THIRD_PARTY_NOTICES.md.
GreenBubbles for Windows is an independent project, not affiliated with or endorsed by Tencent. It is an interoperability implementation without official Tencent authorization; evaluate Tencent's terms and local law before distributing or using it. WeChat and other product names are trademarks of their respective owners.
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
Your own WhatsApp as an MCP server: read, search and send from any MCP client.
WhatsApp MCP on your own number: read chats, search contacts, send messages.
Search contacts, read chats, and send confirmed messages for one Waspy account.
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables agents to drive WeChat 4.x on Windows without hijacking the foreground window, mouse, or keyboard — sending text and file messages through message posting rather than input injection. Also exposes tools for decrypting and querying the local SQLCipher 4 databases to read sessions, chat history, contacts, and group members.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables querying read-only, locally synced WeChat conversations and their messages, listing and verification of cached file attachments, and checking the incremental watcher's status on macOS. Tools are exposed over stdio with configuration via an environment variable, and only perform queries without consuming the notification queue.MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to read the local, already-logged-in WeChat account's chat history: fetch recent messages per contact for reply suggestions, bulk-export all conversations into a local SQLite index for full-text and semantic search, and export media or Moments timelines as offline HTML. Everything runs locally and read-only on macOS, exposing 15 MCP tools plus a matching CLI.GPL 3.0
- AlicenseNot gradedqualityCmaintenanceEnables read-only access to WeChat 3.x and 4.x chat history, including contact search, session listing, message queries by time range, and export to txt without modifying the original databases.MIT