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

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

Tool	What it does
list_chats	Recent chats (DMs + groups) with JIDs and previews
read_messages	Message history of a chat, with paging
search_messages	Full-text search across all stored messages
search_contacts	Find a contact's JID by name or number
send_message	Send text to a phone number or group JID
list_group_participants	Members of a group
get_connection_status	Troubleshooting

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

Command	Purpose
npm run setup	Install, build, print Claude Desktop config
npm run login	Link WhatsApp via QR (one time)
npm run logout	Wipe the local session
npm run build	Recompile after code changes

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.