wazap

```
██╗    ██╗ █████╗ ███████╗ █████╗ ██████╗
██║    ██║██╔══██╗╚══███╔╝██╔══██╗██╔══██╗
██║ █╗ ██║███████║  ███╔╝ ███████║██████╔╝
██║███╗██║██╔══██║ ███╔╝  ██╔══██║██╔═══╝
╚███╔███╔╝██║  ██║███████╗██║  ██║██║
 ╚══╝╚══╝ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝
```

**WhatsApp for your AI agent.** An MCP server that puts your WhatsApp account —
chats, messages, media, contacts, groups — behind 25 tools any MCP client can
call. Pairing-code login, no browser, no phone-number reseller, ~20 MB of RAM.

Built on [Baileys](https://github.com/WhiskeySockets/Baileys), which speaks the
WhatsApp multi-device protocol over a WebSocket.

## Get started

The npm package is `wazap-mcp`; the command it installs is `wazap`.

```bash
npx wazap-mcp setup
```

That is the whole install. It links your account, finds the MCP clients
installed on this machine, writes their config, copies the five skills where
that client reads them, and tells you what to restart. When you started through
`npx`, `setup` offers to install wazap globally so Claude Desktop and the
background service have a path that does not change. It also offers to
`brew install` whisper-cpp, ffmpeg or Tailscale when a step needs one and it is
missing, and to restart Claude Desktop itself once it has connected it.

### Or the path your harness prefers

| Harness | Fastest path |
| --- | --- |
| Claude Code | `/plugin marketplace add razvangirgiz/wazap`, then `/plugin install wazap@wazap` |
| Claude Desktop | download `wazap-<version>.mcpb` from [Releases](https://github.com/razvangirgiz/wazap/releases) and double-click it |
| Gemini CLI | `gemini extensions install https://github.com/razvangirgiz/wazap` |
| Cursor | the [Install in Cursor](#other-mcp-clients) badge, then `npx wazap-mcp skills install cursor` |
| VS Code | the [Install in VS Code](#other-mcp-clients) badge |
| Codex CLI | `npx wazap-mcp connect codex`, then `npx wazap-mcp skills install codex` |
| OpenCode | `npx wazap-mcp connect opencode`, then `npx wazap-mcp skills install opencode` |
| Windsurf | `npx wazap-mcp connect windsurf` |
| Anything else | the MCP entry `npx -y wazap-mcp` over stdio, or a [self-hosted](#self-host) URL |

Each of those registers the server. Linking the WhatsApp account is a separate,
one-time step in every one of them: `npx wazap-mcp login`.

Or have your agent do it. Paste this:

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

Then ask your agent: *"what did I miss on WhatsApp today?"*

Below are the steps `setup` runs for you. Each is still its own command when you
want to run it by hand.

`npx wazap-mcp login` shows a QR code; scan it from **Settings → Linked devices
→ Link a device**. No camera handy, or linking over SSH? `npx wazap-mcp login --phone +15550100`
prints an 8-character code you type under *Link with phone number instead*.
It ends by asking whether the agent may send messages; the answer is no unless
you say yes, and `npx wazap-mcp config writes on` changes it later.

`npx wazap-mcp connect claude-code` writes the MCP entry for one client. The
table under **Connect a client** has the rest.

`npx wazap-mcp` on its own is safe to run: it prints where you stand and what to do
next, and starts no server. When something is off, `npx wazap-mcp status` is the
first thing to run — it checks Node, the data directory, the lock, the
credentials and whether a newer version is out, and prints the fix next to
anything broken.

### Connect a client

`wazap connect <client>` writes the entry for you, keeping whatever else is in
the file and backing it up once before the first change. `--dry-run` shows what
it would write.

| Client | What `connect` writes |
| --- | --- |
| `claude-code` | runs `claude mcp add whatsapp` for you |
| `claude-desktop` | `claude_desktop_config.json` in the Claude application directory |
| `cursor` | `~/.cursor/mcp.json` |
| `codex` | `[mcp_servers.whatsapp]` in `~/.codex/config.toml` |
| `vscode` | `./.vscode/mcp.json`, for the current workspace |
| `gemini` | `~/.gemini/settings.json` |
| `windsurf` | `~/.codeium/windsurf/mcp_config.json` |
| `opencode` | `mcp.whatsapp` in `~/.config/opencode/opencode.json` |
| anything remote | client's MCP URL field: `https://your-host/mcp` with header `Authorization: Bearer <token>`, or just the URL once [OAuth](#hosted-agents-oauth) is on (see [Self-host](#self-host)) |

### Other MCP clients

Cursor and VS Code install from a link:

[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.png)](cursor://anysphere.cursor-deeplink/mcp/install?name=whatsapp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIndhemFwLW1jcCJdfQ)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](vscode:mcp/install?%7B%22name%22%3A%22whatsapp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22wazap-mcp%22%5D%7D)

Both carry the same entry `connect` writes. Where a custom scheme is stripped
before you can click it, VS Code also takes
[the https form](https://insiders.vscode.dev/redirect/mcp/install?name=whatsapp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22wazap-mcp%22%5D%7D).
`node scripts/badges.mjs` reprints all three.

Any other MCP client works the same way: the command is `npx -y wazap-mcp`, the
transport is stdio. Tell the agent to call `learn` first — it returns the id
formats, the workflows and every error code with what to do about it.

<details>
<summary>The raw entries, for editing by hand</summary>

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

Claude Desktop, Cursor, Gemini CLI and Windsurf take exactly that. VS Code nests
it under `servers` and wants a `"type": "stdio"` alongside `command`. Codex CLI
is TOML:

```toml
[mcp_servers.whatsapp]
command = "npx"
args = ["-y", "wazap-mcp"]
```

OpenCode takes the command and its arguments as one array, under `mcp`:

```json
{
  "mcp": {
    "whatsapp": { "type": "local", "command": ["npx", "-y", "wazap-mcp"] }
  }
}
```

</details>

The `skills/` folder follows the [Agent Skills](https://agentskills.io) format, so Codex, Cursor and other skill-aware agents can load the same five skills.

### Gemini CLI

```bash
gemini extensions install https://github.com/razvangirgiz/wazap
```

That reads `gemini-extension.json` at the repo root, so it registers the MCP
server and loads `GEMINI.md` — the five skills below, concatenated, because the
Gemini CLI takes one context file per extension rather than a skills directory.
`wazap connect gemini` writes the server alone, without the context.

`GEMINI.md` is generated: `npm run context:build` rebuilds it from
`skills/*/SKILL.md`, and a test fails if the two have drifted, so a workflow is
only ever edited in its skill.

### Claude Desktop, without a terminal

Download `wazap-<version>.mcpb` from [Releases](https://github.com/razvangirgiz/wazap/releases)
and double-click it. Claude Desktop installs the server, its Node dependencies
and the icon, and shows two settings: **Read-only**, ticked, and **Data
directory**, empty. `wazap connect claude-desktop` does the same job by editing
`claude_desktop_config.json`. Claude Desktop starts its servers without your
shell PATH, so that entry is the absolute path to `node` when wazap is installed
globally, and `npx` otherwise; `wazap setup` checks that the entry it wrote is
one Claude Desktop can actually launch.

Then ask Claude to link your WhatsApp. It calls `link_account` with your number,
hands back an 8-character code, and you type that code into **WhatsApp →
Settings → Linked devices → Link a device → Link with phone number instead**.
No terminal at any point. `npx wazap-mcp login` does the same job from a shell
when you have one.

Untick **Read-only** to let Claude send. It ships ticked because a bundle that
can message people from your number before you have said so is the wrong
default, and because the setting cannot be left unanswered: the manifest format
has no way to omit an argument, so the box you see is the answer the server gets.
`link_account` is registered either way. Read-only exists to stop Claude
messaging people from your number, and relinking your own dead session messages
nobody.

Build it yourself with `npm run bundle:mcpb`, which stages `dist/`, the
manifest, the icon and a fresh production `node_modules`, then packs them with
[`@anthropic-ai/mcpb`](https://github.com/modelcontextprotocol/mcpb).

### Keep it running

A wazap started by a client lives as long as that client does. Quit Claude Code
and the session is gone until you open it again. Two commands change that.
Staying up and being reachable are separate choices.

```bash
npx wazap-mcp service install
```

That writes a launchd agent on macOS (`~/Library/LaunchAgents/com.wazap.server.plist`)
or a systemd user unit on Linux (`~/.config/systemd/user/wazap.service`), starts
it, and waits for `/healthz` to answer. The unit runs `serve --http` on
`127.0.0.1:8766` with the absolute path of this Node and this install, so it
survives a reboot and a logout. Point any client at
`http://127.0.0.1:8766/mcp`, or keep using the stdio entry. A second wazap on
the same data directory becomes a bridge onto the session this one holds.

`service status` prints the pid, the health check and whether the unit still
runs the version you have installed. `service logs` tails it. `service restart`
picks up an upgrade; `service uninstall` removes the unit and leaves your
session and credentials alone. `wazap login` needs the session to itself, so it
stops the service, pairs, and starts it again on its own.

A sleeping Mac is an offline wazap. System Settings → Lock Screen, or Battery →
Options, has the switch that keeps it awake on power.

```bash
npx wazap-mcp expose
```

That gives the running service a public `https` URL, for agents that are not on
this machine: a cloud agent, claude.ai, ChatGPT. It uses