WhatsApp MCP

An MCP server that connects Claude, or any other MCP client, to your personal WhatsApp account. It links to your account as a device, the way WhatsApp Web does, and keeps a searchable copy of your chats on your own computer. From there the assistant can read and search your history, send messages and files, and open the photos and documents people send you.

Things you can ask once it's set up:

• "What are my unread WhatsApp messages?"

• "Summarise what the book club group talked about this week."

• "Find the invoice Alex sent me in August."

• "Tell Sam I'm running ten minutes late."

• "What's in the photo Zoe sent this morning?"

Requirements

• Node.js 22.16 or newer (24 recommended). Older versions' built-in SQLite lacks the full-text search this uses.

• Windows, macOS or Linux

• The phone with the WhatsApp account you want to link

Related MCP server: whatsapp-mcp

Install

git clone https://github.com/ionutsss1/whatsapp-mcp.git
cd whatsapp-mcp
npm install

npm install also builds the server into dist/.

Link your WhatsApp

Use whichever of these is most convenient:

• From your MCP client: once it's connected (next section), ask it to check the WhatsApp connection. The connection_status tool returns a QR code.

• In a browser: run npm run status to start the bridge, then open http://127.0.0.1:47620/link. The page keeps the QR code fresh and also offers linking by phone number.

• In a terminal: npm run login prints the QR code. For an 8-character pairing code instead, run npm run login -- --phone 15555550123 with your own number and country code.

On the phone, go to Linked devices (under Settings on iPhone, the ⋮ menu on Android), then Link a device. This computer then appears in the list as "WhatsApp MCP", and your history syncs over the next few minutes; large accounts take longer.

Connect it to your MCP client

Every client needs the absolute path to dist/mcp.js. Run pwd (macOS/Linux) or cd (Windows) inside the folder to find it.

Claude Code

claude mcp add --scope user whatsapp -- node /absolute/path/to/whatsapp-mcp/dist/mcp.js

Claude Desktop. Add the server to claude_desktop_config.json, which lives in ~/Library/Application Support/Claude/ on macOS and %APPDATA%\Claude\ on Windows:

{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": ["/absolute/path/to/whatsapp-mcp/dist/mcp.js"]
    }
  }
}

Quit Claude Desktop completely and reopen it. Closing the window isn't enough, because the app keeps running in the tray or menu bar. If the server doesn't start, Claude Desktop probably can't find node: replace "node" with its full path, which which node or where node prints. On Windows that is something like "C:\\Program Files\\nodejs\\node.exe", with the backslashes doubled as JSON requires.

Other clients. Any client that runs local (stdio) servers works: the command is node, and its one argument is the path to dist/mcp.js.

Tools

Sending is deliberately strict about the recipient. It accepts a chat ID, a phone number with country code, an exact contact or group name, or "myself". A partial or ambiguous name is refused with a list of candidates, so a message never goes to a best guess.

How it works

MCP client ──stdio──> dist/mcp.js ──reads──> data/whatsapp.db  (SQLite + full-text index)
                           │                        ^
                           └──HTTP 127.0.0.1──> dist/bridge.js ──WebSocket──> WhatsApp

• The bridge is a single background process. It holds the WhatsApp connection, mirrors chats, contacts and messages into SQLite, and does all sending and downloading. The MCP server starts it when needed, and it keeps running after your client exits, so messages keep syncing.

• The MCP server is what the client talks to. It reads straight from SQLite and passes everything else to the bridge over localhost.

The two are separate on purpose. Clients start one MCP server per session, and two connections using the same session keys knock each other offline. However many sessions and apps you run, they all share the one bridge.

Privacy and safety

• Your data stays local. History lives in data/whatsapp.db. The only other connections the bridge makes are to WhatsApp itself and to GitHub, to check which WhatsApp Web version Baileys currently supports.

• It stays quiet. The bridge doesn't mark you as online, so your phone keeps its notifications, and it never sends read receipts (blue ticks).

• Deletions are respected. Messages deleted for everyone are wiped locally too. View-once media is only ever delivered to the phone, so it can't be opened here.

• The local API is locked down. The bridge only listens on 127.0.0.1 and needs a random token, which is stored in data/bridge-token. It also rejects foreign Host and Origin headers, so no web page can send messages through it.

• Messages are data, not instructions. Messages are written by other people. The server tells the assistant never to act on instructions inside them, and every result that contains message text repeats that warning. Most clients also ask you before each send.

Day to day

npm run status   # connection state and sync counts
npm run stop     # stop the bridge (you stay linked; it restarts when needed)
npm run logout   # unlink this computer from WhatsApp and delete the session keys

• Log: the bridge writes to data/bridge.log, rotated at 5 MB.

• Downloads: saved to data/media/<chat>/ unless you pass save_to_dir.

• Removing everything: run npm run logout, then delete the data/ folder.

Configuration

Set these for both processes; with an MCP client, set them in its server config (env).

Troubleshooting

• No QR code, and the log says 428 Connection Terminated. WhatsApp now drops clients that claim to be the native Windows or Mac desktop app (Browsers.windows('Desktop') in Baileys). The bridge identifies as ['WhatsApp MCP', 'Desktop', …], which still gets the full history. Keep it that way if you fork this.

• State logged_out. The device was removed on the phone. Link it again.

• State replaced. Something else connected with the same keys, usually a second copy of data/. Stop that copy, then run npm run stop so the bridge starts fresh.

• Old media won't download. WhatsApp expires media after a while. The bridge asks the phone to upload it again, which only works if the phone is online and still has the file.

• Contacts show as ~Name. A name with ~ is the one the person set for themselves. Linked devices only get the names your phone chooses to share; WhatsApp Web shows the same thing.

Development

npm test        # builds, then runs the offline test suite; no WhatsApp account needed
npm run smoke   # checks every tool against your own linked account; prints only headers

WhatsApp is moving people from phone numbers to LIDs, private per-account IDs (…@lid). The store keeps each person under their phone number once the LID↔phone mapping is known, and moves anything filed under a LID as soon as the mapping arrives.

License

MIT. This project is not affiliated with, endorsed by or connected to WhatsApp or Meta.