Zappy

WhatsApp MCP server enabling per-chat permissions for send, read, and delete actions across MCP clients.

javascript

0

GitHub Stars

javascript

Language

6 months ago

First Indexed

3 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "brendandebeasi-zappy-mcp": {
      "command": "node",
      "args": [
        "/path/to/zappy-mcp/src/index.js",
        "--config",
        "/path/to/config.json"
      ]
    }
  }
}

You run a dedicated MCP server that connects to WhatsApp Web via automation, enabling your MCP clients to send, read, and delete messages with granular per-chat permissions. This server keeps a WhatsApp session locally, so you authenticate once and reuse that session across configurations and projects.

How to use

Install and start the MCP server, then configure your MCP clients to talk to it. The server maintains a local session with WhatsApp so you can grant per-chat permissions and control exactly which conversations the AI may access. Use the status and messaging tools to manage connections, simulate interactions, and enforce security boundaries.

How to install

Prerequisites: Node.js installed on your machine. You do not need root access for normal operation, but you do need permission to create files in your config and auth directories.

Steps to install and run the MCP server locally:

Additional configuration and usage notes

This MCP server uses a local WhatsApp session stored under the user’s configuration directory. You authenticate once by scanning a QR code, and the session is reused on subsequent runs. Different MCP configs can share the same WhatsApp session while enforcing their own per-chat permissions.

Security and permissions

By default, no chats are allowed. You explicitly grant access per chat with canSend, canRead, and canDelete permissions in your config. Protect the auth data as you would a password, and ensure the QR code is scanned only on trusted devices.

Troubleshooting

If messages stall or authentication fails, restart the MCP server after re-authenticating. Clear session data if needed and re-scan the QR code to re-establish a login.

Tools and capabilities

Available tooling includes status checks, permission listings, chat discovery, and message actions. Use these tools to observe connection health, enumerate allowed chats, view IDs, and perform permitted messaging actions within your configured scope.

Notes on installation and run flow

If you are using a desktop agent or a project with its own MCP manifest, you will reference the local runtime command and point to your chosen config file. The runtime typically runs the index script with a --config flag.

Available tools

get_status

Check WhatsApp connection status and show config and auth locations.

list_allowed

Show all permitted chats with their current permissions.

list_chats

List all WhatsApp chats with IDs to identify conversation targets.

send_message

Send a message to a chat. Requires canSend permission.

get_messages

Fetch recent messages from a chat. Requires canRead permission.

delete_message

Delete a message you sent. Requires canDelete permission and only affects messages sent by you.