Skip to main content
Glama
GreenBubbles for Windows MCP Server

GreenBubbles for Windows MCP Server

by seaneer

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

  1. Download greenbubbles-win-<version>-portable.zip from Releases.

  2. Unzip it anywhere.

  3. Sign in to WeChat and keep it running.

  4. Check access:

.\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.

Agent access

Start the loopback-only connector on the Windows PC:

.\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:

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:

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 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-token

Then 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 .\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 and FAQ.

Documentation

I want to...

Read

Use the CLI, HTTP API or MCP

INTERFACE.md

Give another agent access

AGENT-PROMPT.md

Run a background service

SERVICE.md

Understand the design

ARCHITECTURE.md

Review regression coverage

REGRESSION-TESTS.md

Read this page in Chinese

README.zh-CN.md

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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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