wa-mcp - WhatsApp MCP server for Claude Desktop

Lets Claude read and send WhatsApp messages (DMs and groups) through your own WhatsApp account. Uses Baileys (direct WebSocket, no browser) and stores messages locally in SQLite.

Prerequisites

• Node.js 20+ - check with node --version (download).

• Claude Desktop installed (download).

• git to clone the repo (or download the ZIP from GitHub).

• A phone with WhatsApp installed (for the one-time QR link).

Related MCP server: WhatsApp MCP Server

Setup (3 steps)

# 0. Clone the repo and enter the folder
git clone https://github.com/JaromirSvaton/WA-MCP.git
cd WA-MCP

# 1. Install + build + show the Claude Desktop config for your machine
npm run setup

# 2. Link your WhatsApp (one time only) - scan the QR with your phone:
#    WhatsApp > Settings > Linked Devices > Link a Device
npm run login

# 3. Paste the config printed by step 1 into:
#    %APPDATA%\Claude\claude_desktop_config.json
#    then fully restart Claude Desktop (quit from system tray, reopen).

If the QR code looks garbled in your terminal, run chcp 65001 first or use Windows Terminal.

Configuring Claude Desktop manually

npm run setup (or npm run print-config) prints a snippet with absolute paths for your machine. It looks like this:

{
  "mcpServers": {
    "whatsapp": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\path\\to\\WA-MCP\\dist\\index.js"]
    }
  }
}

Open %APPDATA%\Claude\claude_desktop_config.json (create it if it doesn't exist), paste the snippet, and if the file already has an "mcpServers" object, merge the "whatsapp" entry into it. Then fully quit Claude Desktop from the system tray and reopen it. You should see the WhatsApp tools available in a new chat.

Tools exposed to Claude

How it works

• All data lives in ~/.wa-mcp/ (session keys in auth/, messages in messages.db). Treat auth/ like a private key - anyone with those files can hijack your WhatsApp session.

• Messages are ingested into SQLite while the server runs (Claude Desktop keeps it running in the background). History from before the first login is only partially available - WhatsApp sends a limited recent-history sync.

• Claude Desktop asks for your approval before every send_message call.

Commands

Troubleshooting

• "Not logged in" - run npm run login, then restart Claude Desktop.

• Server not showing in Claude - check the config file is valid JSON and paths are absolute; view logs at %APPDATA%\Claude\logs\mcp*.log.

• Logged out randomly - WhatsApp occasionally drops linked devices; run npm run login again.

• Ban risk - this uses an unofficial API. Keep usage personal and low-volume; don't send bulk/automated spam.