Skip to main content
Glama
GreenBubbles for Windows MCP Server

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.