Wazap

╭───────────────╮

│ ▄██▀ │ ██╗ ██╗ █████╗ ███████╗ █████╗ ██████╗ │ ▄██▀ │ ██║ ██║██╔══██╗╚══███╔╝██╔══██╗██╔══██╗ │ ▄███████▀ │ ██║ █╗ ██║███████║ ███╔╝ ███████║██████╔╝ │ ▄██▀ │ ██║███╗██║██╔══██║ ███╔╝ ██╔══██║██╔═══╝ │ ▄█▀ │ ╚███╔███╔╝██║ ██║███████╗██║ ██║██║ ╰─╮╭────────────╯ ╚══╝╚══╝ ╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚═╝ ╰╯ WhatsApp for your AI agent.

wazap is an MCP server for your own WhatsApp account. It links as a device, the way WhatsApp Web does, keeps what it sees on your machine, and gives any MCP client — Claude, ChatGPT, Gemini, Cursor, Codex — 23 tools over your chats, messages, media, contacts and groups.

You stop opening WhatsApp to find things and ask instead:

• *"What did I miss on WhatsApp today?"* — one answer across every linked account: who is waiting on you, mentions, missed calls, busy groups condensed.
• *"Find the invoice Dan sent in spring."* — search by meaning and by words at once, then open the file.
• *"What did the voice note from mama say?"* — voice notes come back as text.
• *"Tell Ana I'll be twenty minutes late."* — you see the recipient and the exact words first. Nothing leaves until you say yes.

No browser, no business account, no third-party service. There is no wazap cloud: it runs where you run it.

Get started

You need Node.js 22.16+ on the 22 line, or 24+, and a phone with WhatsApp.

npx wazap-mcp setup

setup links your account, finds the MCP clients installed on this machine (Claude Code, Claude Desktop, Cursor, Codex, Gemini CLI), writes their config, installs the five skills where the client reads them, and tells you what to restart. Then ask your assistant: *"what did I miss on WhatsApp today?"*

Rather let your agent do it? Paste this into it:

Set up WhatsApp for me: run npx wazap-mcp setup --agent and follow what it prints.

npx wazap-mcp on its own, in a terminal, starts nothing: it prints where you stand and the next command. When something is off, npx wazap-mcp status is the first thing to run; it prints a fix next to anything broken.

Per client

The hand-written entry, for any client that takes the usual JSON:

{

"mcpServers": { "whatsapp": { "command": "npx", "args": ["-y", "wazap-mcp"] } } }

Every step setup takes, each file connect writes, and upgrading are in docs/install.md.

Linking your account

Linking is a one-time step. setup does it for you; on its own it is:

npx wazap-mcp login                      # QR code: Settings → Linked devices → Link a device

npx wazap-mcp login --phone +15550100 # pairing code instead, no camera needed

With --phone, wazap prints an 8-character code. On the phone, go to WhatsApp → Settings → Linked devices → Link a device → Link with phone number instead and type it in. The pairing code works over SSH and on a headless server, where a QR is impractical.

An assistant can link the account itself, too: the link_account tool returns the same code, so a Claude Desktop user never needs a terminal.

Several WhatsApp accounts can live in one wazap (wazap account add , then wazap login --account ); see docs/accounts.md.

The 23 tools

What every argument means, and every error code, is in docs/tools.md. The assistant gets all of it by calling learn.

Scheduled messages and reminders. send_message with send_at ("tomorrow at 9" as 2026-10-12T09:00 in Europe/Bucharest) drafts a message for later; the user's yes to that preview, time included, schedules it, and every send check runs again when it goes. One wazap could not send within 15 minutes of its time is reported as missed, never sent late. reminder keeps "remind me if Ana has not answered in 2 days" and posts it to your webhook when due. Both survive restarts; see Scheduling a message and Reminders.

Two features are off by default and can run entirely on your machine: voice transcription with whisper.cpp (docs/voice.md) and semantic recall, so search matches meaning and not only words (docs/recall.md). Turn them on with wazap config transcribe local and wazap config recall local.

Skills

Tools say what is possible; the five Agent Skills in skills/ say how to do the job well.

setup installs them for Claude Code, Codex and Cursor (npx wazap-mcp skills install does it by hand). Every other client gets the same five as MCP prompts from the server, with nothing to install.

Transports

stdio is the default: the client starts npx -y wazap-mcp and talks to it over stdin/stdout. Nothing listens on the network.

HTTP (Streamable HTTP) is for a server that outlives the client, or one another machine reaches:

npx wazap-mcp serve --http                 # http://127.0.0.1:8766/mcp, health at /healthz

--host/--port (or WAZAP_HOST/WAZAP_PORT) move it. wazap refuses to bind anything but loopback without WAZAP_READ_TOKEN. Clients authenticate with a static bearer token (WAZAP_READ_TOKEN, plus WAZAP_WRITE_TOKEN for the write tools) or with OAuth 2.1, which wazap serves itself. Details in docs/self-host.md.

Remote access

Two commands keep wazap running and reachable from hosted agents:

npx wazap-mcp service install   # a launchd agent (macOS) or systemd user unit (Linux)

npx wazap-mcp expose # a public https URL through Tailscale Funnel or Cloudflare Tunnel

expose prints the URL and a consent password. Give the agent only the URL; it registers itself, and the consent page asks you for the password and whether that agent may only read or also send. See Keep it running.

The service recovers by itself: a dropped link is retried with backoff, a watchdog replaces a socket that went dead across a sleep or stopped answering, and when reconnecting keeps failing wazap exits so launchd or systemd starts it fresh. The linked session is never deleted for any of that; only WhatsApp unlinking the device needs a new link. Set WAZAP_WEBHOOK_EVENTS to include alert to be told when the link has been down for 5 minutes, when it is back, and when it needs linking again (Link alerts); get_status shows the same under link.

Deployment

On a server of your own, the session never leaves it. With Docker (images for amd64 and arm64 at ghcr.io/razvangirgiz/wazap):

mkdir wazap && cd wazap

curl -fsSLO https://raw.githubusercontent.com/razvangirgiz/wazap/main/docker-compose.yml printf 'WAZAP_READ_TOKEN=%s\nWAZAP_WRITE_TOKEN=%s\n' $(openssl rand -hex 32) $(openssl rand -hex 32) > .env docker compose run --rm wazap login --phone +15550100 # once; the session lands in the volume docker compose up -d curl -s http://127.0.0.1:8766/healthz

The container publishes port 8766 on loopback only; put TLS in front (deploy/Caddyfile is two lines). A systemd unit is in deploy/wazap.service. Both setups, reverse-proxy trust and the OAuth server are in docs/self-host.md. Calling wazap from your own product, and receiving signed webhooks for incoming messages, is in docs/api-and-webhooks.md.

Configuration

Every setting is optional. They are environment variables, read from the process or from `~/