WhatsApp MCP Server

WhatsApp MCP — Local

Connect your WhatsApp to Claude Desktop. Everything stays on your machine — no cloud, no servers, developer sees nothing.

📦 All messages stored in a local SQLite database (~/.whatsapp-mcp/whatsapp.db)
🔒 Auth keys stored only in ~/.whatsapp-mcp/session/ — never leave your machine
🔍 Full-text search across complete chat history
📥 Import old chats via WhatsApp's Export Chat feature

Prerequisites

Node.js v20+ — download from nodejs.org (LTS version)
Claude Desktop — download from claude.ai/download
Git — download from git-scm.com

Setup (Fresh Machine)

Windows — double-click installer

Install Node.js LTS if you don't have it
git clone https://github.com/khetsinghrajput/WhatsApp-MCP-Local.git
Open the cloned folder → double-click install.bat

That's it. The batch file handles npm install and config automatically. No PowerShell, no manual editing.

Mac / Linux — terminal

git clone https://github.com/khetsinghrajput/WhatsApp-MCP-Local.git
cd WhatsApp-MCP-Local
make install

No make? Use: chmod +x install.sh && ./install.sh

Manual (any platform)

npm install
npm run setup

Windows PowerShell error? If you see "running scripts is disabled", run this once in PowerShell then retry:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
Or just use install.bat instead — it uses cmd.exe which never has this problem.

Output looks like:

✅ Done! Config written:
   Server  : whatsapp
   Command : C:\Program Files\nodejs\node.exe
   Script  : C:\Users\You\WhatsApp-MCP-Local\src\index.ts

📋 Next steps:
   1. Fully quit Claude Desktop (system tray → Quit)
   2. Reopen Claude Desktop
   3. Your browser opens at http://localhost:3000 — scan the QR with WhatsApp
   4. Done! Use whatsapp_status in Claude to confirm.

After setup

Quit and reopen Claude Desktop
Browser auto-opens at http://localhost:3000 — scan the QR
Wait a few minutes for history to sync

Check progress in Claude:

whatsapp_status
→ 📦 1,240 messages stored across 108 chats
→ 📅 History goes back to: 25/05/2025

Available Tools

Tool	What it does
`whatsapp_status`	Connection status + database stats
`whatsapp_list_chats`	All chats sorted by most recent
`whatsapp_list_groups`	Group chats only
`whatsapp_find_contact`	Search contacts by name or phone number
`whatsapp_get_messages`	Read messages from a chat (full history)
`whatsapp_send_message`	Send a message
`whatsapp_search_messages`	Full-text search across all messages

Import Old Chats

WhatsApp only sends recent history during initial sync. To get older messages:

Step 1 — Export from your phone

Open the chat in WhatsApp
Tap ⋮ → More → Export Chat
Choose Without Media
Send the .txt file to your computer

Step 2 — Run the importer

First find the contact's JID using whatsapp_find_contact "Their Name" in Claude, then:

npm run import -- "C:/path/to/WhatsApp Chat with John Doe.txt" "[email protected]" "John Doe"

The importer shows:

✅ Import complete!
   Contact  : John Doe
   Messages : 1,847 imported
   Range    : 15/03/2023 → 17/05/2026

📦 Database now has 3,091 messages across 109 chats

Messages are de-duplicated automatically — safe to run multiple times.

Your Data

~/.whatsapp-mcp/
  session/          ← WhatsApp auth keys (never shared)
    creds.json
    pre-key-*.json
  whatsapp.db       ← All messages, searchable forever

To unlink from WhatsApp: Phone → Settings → Linked Devices → find WhatsApp MCP → Log Out. Then delete ~/.whatsapp-mcp/session/ and restart Claude Desktop — you'll get a new QR.

To fully remove: Delete ~/.whatsapp-mcp/ and remove the mcpServers block from the config.

Troubleshooting

"Server disconnected" error on Windows: Make sure you used tsx.cmd (not tsx) in the config and paths use / not \.

Browser doesn't open automatically: Visit http://localhost:3000 manually.

Chats show as numbers instead of names: Normal on first connect — names load as WhatsApp syncs contacts. Wait 30 seconds and check again.

Contact not found: Use whatsapp_find_contact "name" — if it shows "no messages synced yet", export the chat and use the importer.

Documentation