Skip to content
🤖 New in v0.5.0

Connect WhatsApp to
your AI

Let Claude (or another assistant) read your messages, reply and transcribe audio right inside WhatsApp. No coding needed: just follow the steps below. Everything runs on your machine, nothing goes through an external server.

First things first: have the ZeroZapp extension installed and WhatsApp Web open and logged in. The rest is the step-by-step below, from scratch.

1

Install Node.js

Why this? The ZeroZapp server is a little JavaScript program, and Node.js is the engine that runs it on your machine. It is free, you install it once and forget about it.

  1. Go to nodejs.org
  2. Download the button that says "LTS" (the stable version)
  3. Open the downloaded file and keep clicking continue until it finishes

Want to confirm it worked? Open the Terminal app (on Mac, search "Terminal" in Spotlight) and paste this:

node --version

Press Enter. If a number like v20.11.0 shows up, you are all set.

2

Connect to your AI client

Pick the program you use:

Claude Desktop

Copy this configuration (it is the address that tells Claude how to find ZeroZapp):

{
  "mcpServers": {
    "zerozapp": {
      "command": "npx",
      "args": ["-y", "@zerozapp/mcp"]
    }
  }
}

Now paste it into Claude Desktop:

  1. Open the Claude → Settings menu (or press Cmd + comma)
  2. Go to the Developer tab and click Edit Config
  3. Paste what you copied and save the file
  4. Quit Claude completely and open it again

💡 If the file already has other servers, paste only the "zerozapp" block inside "mcpServers". The file lives at ~/Library/Application Support/Claude/claude_desktop_config.json.

Claude Code / Cursor

These programs edit files on their own, so the easiest way is to ask them. Paste this prompt into the assistant itself:

Add an MCP server called "zerozapp" to my config, with command "npx" and args ["-y", "@zerozapp/mcp"]. Then tell me how to restart to activate it.

Prefer doing it by hand? In Claude Code, one terminal command does it:

claude mcp add zerozapp -- npx -y @zerozapp/mcp

In Cursor, paste the same configuration from the "Claude Desktop" tab into the ~/.cursor/mcp.json file. Then restart the client.

3

Enable the bridge in the extension

Open the ZeroZapp extension, go to Settings → MCP and turn on Enable MCP bridge. Once connected, the badge turns Connected and your account shows up in the list.

🔒 If the machine is shared, set a token: add "env": { "ZEROZAPP_MCP_TOKEN": "your-secret" } to the step 2 config and put the same token in the extension.

4

Done! Ask your AI for something

With WhatsApp Web open and the bridge connected, just ask for things like:

  • “List my unread conversations on WhatsApp.”
  • “Send "on my way" to 5511999999999.”
  • “Find André's number and send the PDF at /tmp/report.pdf.”
  • “Transcribe the last audio Maria sent me.”
What the AI can do

There are 16 tools exposed, organized into three groups:

🔍 Discovery

  • list_accountsLists the connected WhatsApp accounts
  • list_chatsRecent conversations with unread counts
  • get_recent_messagesLast message from each conversation, for quick triage
  • find_contactSearches contacts and chats by name or phone
  • list_group_participantsLists the participants of a group

📖 Reading

  • get_messagesReads messages with filters (sender, search, media, etc)
  • transcribe_audioTranscribes a voice note or audio (Whisper)
  • get_imageDownloads an image or sticker
  • get_documentDownloads a document (PDF, DOCX, ZIP...)
  • get_videoDownloads a video

✉️ Sending and actions

  • send_messageSends a text message
  • send_imageSends an image with an optional caption
  • send_documentSends a document (PDF, DOCX, ZIP...)
  • react_to_messageReacts to a message with an emoji
  • open_chatOpens a conversation in the WhatsApp interface
  • archive_chatArchives or unarchives a conversation

The account parameter is the number part of the WhatsApp ID (e.g. 5511999999999). It is only needed when you have more than one account connected.

How it works under the hood

The MCP server runs locally on your machine and talks to the extension over WebSocket. Your AI client talks to that server, which relays the commands to WhatsApp Web open in your browser.

AI client  ──stdio──▶  @zerozapp/mcp server  ──WebSocket──▶  ZeroZapp extension
                                                                  │
                                                                  ▼
                                                             WhatsApp Web

That npx -y @zerozapp/mcp line in the config is what downloads and starts the server automatically (npx comes with Node). You can change the port with ZEROZAPP_MCP_PORT (default 9223); the WebSocket URL in the extension is ws://127.0.0.1:9223.

Hit a snag?

“No accounts connected”

Check that WhatsApp Web is open and logged in, and that the bridge is enabled in Settings → MCP.

“The extension keeps reconnecting”

Confirm the port matches and the token is identical on both sides. The log lives in zerozapp-mcp-daemon.log (in the system temp folder).

“auth_required and it disconnects”

The extension token and the server token are different. Make them the same.

“The tool times out”

WhatsApp's Window.Store may not be ready. Reload WhatsApp Web and try again.

Privacy and security
  • The server listens only on 127.0.0.1, it is never reachable over the network
  • The bridge ships off by default: it only turns on when you enable it
  • Set a token whenever the machine is shared, and treat it like a password
  • The bridge can read all your messages and send messages on your behalf

Don't have ZeroZapp yet?

Install the extension and enable the MCP bridge in just a few minutes.

Install from the Chrome Web Store