WACrew

Guide

whatsapp-mcp setup problems and how to fix them

Common errors when installing lharries/whatsapp-mcp and its forks: CGO on Windows, uv not found, QR code not showing, device limit, empty history and out-of-sync databases, with the fix for each.

Updated 3 min read
On this page
  1. "Binary was compiled with CGO_ENABLED=0, go-sqlite3 requires cgo to work"
  2. The client says the server failed to start, or "uv: command not found"
  3. Tools show up but return nothing
  4. The QR code does not appear
  5. "Device limit reached"
  6. Messages out of sync
  7. Asked to scan again after a few weeks
  8. Voice notes do not play
  9. When to stop fighting the setup
  10. FAQ

Most problems with lharries/whatsapp-mcp and its forks come from the two-process setup: a Go bridge that holds the WhatsApp session and a Python MCP server that your client starts. Here are the errors people hit most, with fixes drawn from the project's own troubleshooting notes.

"Binary was compiled with CGO_ENABLED=0, go-sqlite3 requires cgo to work"

You are on Windows. go-sqlite3 needs CGO and a C compiler, and CGO is off by default there. Install a compiler (the README suggests MSYS2 and adding ucrt64\bin to PATH), then:

cd whatsapp-bridge
go env -w CGO_ENABLED=1
go run main.go

The client says the server failed to start, or "uv: command not found"

The JSON config needs absolute paths: the output of which uv for command, and the full path to whatsapp-mcp-server in args. Clients like Claude Desktop do not load your shell PATH, so uv alone often fails. Restart the client after editing claude_desktop_config.json or ~/.cursor/mcp.json.

Tools show up but return nothing

Both processes must run. The Python server reads what the Go bridge stores, so if the bridge is not running in a terminal (or as a service), searches come back empty and sends fail. After the first pairing, history can take several minutes to load.

The QR code does not appear

Restart the bridge. If your terminal cannot render the QR code, try another terminal. If a session already exists, the bridge reconnects without showing a QR code at all, which is expected.

"Device limit reached"

WhatsApp caps linked devices. Remove an old one on your phone under Settings, Linked devices, then link again.

Messages out of sync

Stop the bridge, delete whatsapp-bridge/store/messages.db and whatsapp-bridge/store/whatsapp.db, start again and re-scan. You will lose the local history and resync from what the phone sends.

Asked to scan again after a few weeks

The README warns that re-authentication may be needed after about 20 days. Keep the bridge running continuously to reduce how often that happens.

Voice notes do not play

To send a playable voice note the file must be Ogg Opus. Install FFmpeg so send_audio_message can convert MP3 or WAV; without it, send_file sends a plain audio file.

When to stop fighting the setup

If you keep hitting runtime issues, two routes avoid Go and Python entirely:

FAQ

Is the Python server or the Go bridge the one that talks to WhatsApp? The Go bridge. The Python server only speaks MCP and reads the database or calls the bridge.

Why does my agent miss messages from last night? WhatsApp delivers a message to the devices online at the time. If the bridge was off, those messages may not reach its database. A server that runs 24/7 fixes that.

Do these fixes apply to the forks? Mostly yes. verygoodplugins/whatsapp-mcp and whatsapp-mcp-extended share the Go plus Python design, with their own extra settings.