# Whatsapp MCP

> Install and manage the WhatsApp MCP for Claude Desktop / Claude Code on macOS. Bridge syncs WhatsApp Web → local SQLite; the patched MCP server resolves contacts against the user's iPhone/Android address book (no more raw phone numbers in query results). Use when asked to "install whatsapp", "set up whatsapp mcp", "connect whatsapp to claude", or any first-time WhatsApp + Claude setup. Also handles --update, --uninstall, --reimport.

- Skill: `adam-s-builder-club/whatsapp-mcp` (Agent Skill)
- Install (CLI): `npx skillmds@latest add adam-s-builder-club/whatsapp-mcp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/adam-s-builder-club/whatsapp-mcp/raw
- Safety review: pending (external: skill-scanner WARNING, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Adam-s-Builder-Club (https://skillmd.com/u/adam-s-builder-club)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/adam-s-builder-club/whatsapp-mcp

---


# /whatsapp-mcp

Installs github.com/lharries/whatsapp-mcp pinned to a known-good SHA, builds the Go bridge, patches the Python MCP server's name resolution against the user's iPhone/Android contacts, writes the Claude Desktop + Claude Code MCP config blocks, and installs a launchd plist that auto-starts the bridge on login.

## What this skill does

1. Checks platform (macOS only for v0.1.x)
2. Installs Homebrew, Go ≥1.25, uv (if missing)
3. Clones lharries/whatsapp-mcp and pins to upstream PR #253 fix-405 branch (asserts SHA equality — aborts on mismatch with clear remediation)
4. Builds the Go bridge
5. Patches the Python MCP server's dataclass `__post_init__` so chat/contact/message names resolve against `~/.whatsapp-mcp/contacts.json`
6. Writes the `whatsapp` MCP entry to both `claude_desktop_config.json` and `~/.claude.json` (atomic, preflight-validated)
7. Installs a launchd plist with `WorkingDirectory` + log paths + `ThrottleInterval=30` (per-user filename so multi-user Macs don't clobber each other)
8. Runs the bridge in the foreground first so the user can see + scan the QR code, then hands off to launchd once `"✓ Connected to WhatsApp!"` log line appears
9. Tells the user to run `/whatsapp-import-contacts` to populate name resolution

## How to invoke

```bash
bash ~/.whatsapp-mcp/skill-repo/install.sh
```

If the skill repo isn't cached locally yet (first-time run via slash command), bootstrap it:

```bash
curl -fsSL https://raw.githubusercontent.com/Adam-s-Builder-Club/whatsapp-mcp-skill/v0.1.1/install.sh | bash
```

Day-2 commands:

```bash
bash ~/.whatsapp-mcp/skill-repo/install.sh --update      # pull latest skill release, re-patch, restart bridge
bash ~/.whatsapp-mcp/skill-repo/install.sh --reauth      # bootout + re-scan QR (after 20-day session expiry or repeated auth-failure)
bash ~/.whatsapp-mcp/skill-repo/install.sh --reimport    # re-import contacts from vCard + macOS Contacts.app
bash ~/.whatsapp-mcp/skill-repo/install.sh --uninstall   # stop bridge, remove launchd plist, un-merge Claude config
```

## What to tell the user before running

Before kicking off the install, surface:

1. The install will request macOS permissions (Contacts via TCC, possibly Homebrew sudo on a clean Mac).
2. The user will need to **scan a QR code with their phone's WhatsApp app** during install (Settings → Linked Devices → Link a Device).
3. After install they should restart Claude Desktop / Claude Code so the new MCP server is picked up.
4. **Security caveat (light touch):** WhatsApp MCPs are subject to the "lethal trifecta" — once installed, prompt-injected content arriving via WhatsApp could in theory cause the model to exfiltrate other messages. See the repo README for the full caveat. Don't pair this skill with auto-reply / auto-forward skills.

## How to detect already-installed

If `~/.whatsapp-mcp/skill-repo/` exists and `launchctl print gui/$(id -u)/com.user.$USER.whatsapp-bridge` returns success, the skill is already installed. Suggest `--update` (latest release), `--reimport` (refresh contacts), or `--uninstall` (clean removal) instead of re-running install.

## After install

Recommend the user immediately run `/whatsapp-import-contacts` so chat/contact names resolve against their real address book instead of showing raw phone numbers like `919949938166@s.whatsapp.net`.