GreenBubbles for Windows MCP Server
by seaneer
README.md
<p align="center">
<img src="assets/greenbubbles-icon.svg" width="132" alt="GreenBubbles for Windows">
</p>
<h1 align="center">GreenBubbles for Windows</h1>
<p align="center">
<strong>Let your agents read your own WeChat history. Locally.</strong><br>
Read-only CLI + HTTP connector + MCP server for Windows WeChat 4.x.<br>
No export step. No second copy to keep in sync.
</p>
<p align="center">
<a href="#install">Install</a> ·
<a href="#usage">CLI usage</a> ·
<a href="#agent-access">Agent access</a> ·
<a href="#archive-and-snapshot">Archive</a> ·
<a href="docs/README.md">Docs</a> ·
<a href="README.zh-CN.md">中文</a> ·
<a href="CONTRIBUTING.md">Contribute</a>
</p>
<p align="center">
<a href="https://github.com/seaneer/greenbubbles-win/actions/workflows/ci.yml"><img src="https://github.com/seaneer/greenbubbles-win/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
<a href="https://github.com/seaneer/greenbubbles-win/releases"><img src="https://img.shields.io/github/v/release/seaneer/greenbubbles-win?include_prereleases" alt="Release"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-22c55e" alt="License: MIT"></a>
<img src="https://img.shields.io/badge/platform-Windows%2010%2F11-0ea5e9" alt="Platform: Windows 10/11">
<img src="https://img.shields.io/badge/WeChat-4.x-07c160" alt="WeChat 4.x">
<img src="https://img.shields.io/badge/python-3.10%2B-3776ab" alt="Python 3.10+">
<img src="https://img.shields.io/badge/status-beta-f59e0b" alt="Status: beta">
</p>
<p align="center">
<img src="assets/architecture.svg" alt="GreenBubbles reads WeChat's encrypted local data, answers agent queries, and can create an optional encrypted snapshot" width="900">
</p>
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.
## Install
1. Download `greenbubbles-win-<version>-portable.zip` from [Releases](https://github.com/seaneer/greenbubbles-win/releases).
2. Unzip it anywhere.
3. Sign in to WeChat and keep it running.
4. Check access:
```powershell
.\greenbubbles.cmd source status
```
The 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 | `greenbubbles.cmd chats --limit 20` |
| Find a chat by name | `greenbubbles.cmd chats find "keyword"` |
| Read one chat and time range | `greenbubbles.cmd messages list --conversation <id-or-name> --since 2026-11-01 --until 2026-11-19` |
| Search message text | `greenbubbles.cmd messages search --query "keyword"` |
| Fetch one message | `greenbubbles.cmd message get --conversation <id> --message-id <id>` |
| Include attachment metadata | add `--with-media` |
| Export with files | `greenbubbles.cmd archive export --out <dir> --formats md,jsonl,html --attachments` |
| Update an archive | `greenbubbles.cmd archive update --out <dir> --attachments` |
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](docs/INTERFACE.md).
## Agent access
Start the loopback-only connector on the Windows PC:
```powershell
.\start-connector-local.cmd
```
It 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:
```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 Allow
```
Confirm both commands report the expected state:
```powershell
Get-WindowsCapability -Online -Name OpenSSH.Server* # State: Installed
Get-Service sshd # Status: Running
```
If 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](docs/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:
```bash
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-token
```
Then an agent calls:
```bash
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](docs/INTERFACE.md) ·
agent prompt: [AGENT-PROMPT.md](docs/AGENT-PROMPT.md) ·
background service: [SERVICE.md](docs/SERVICE.md).
## Archive and snapshot
```powershell
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 .\restored
```
`archive 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.
- `wxgf` images 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](docs/KNOWN_LIMITATIONS.md) and [FAQ](docs/FAQ.md).
## Documentation
| I want to... | Read |
| --- | --- |
| Use the CLI, HTTP API or MCP | [INTERFACE.md](docs/INTERFACE.md) |
| Give another agent access | [AGENT-PROMPT.md](docs/AGENT-PROMPT.md) |
| Run a background service | [SERVICE.md](docs/SERVICE.md) |
| Understand the design | [ARCHITECTURE.md](docs/ARCHITECTURE.md) |
| Review regression coverage | [REGRESSION-TESTS.md](docs/REGRESSION-TESTS.md) |
| Read this page in Chinese | [README.zh-CN.md](README.zh-CN.md) |
All docs: [docs/README.md](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](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
## License
MIT. See [LICENSE](LICENSE), [NOTICE.md](NOTICE.md) and
[THIRD_PARTY_NOTICES.md](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.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues