FAQ
Frequently asked questions
Everything we get asked over and over. If yours isn’t here, open a GitHub issue or book 15 minutes.
- What is an MCP server?
- Model Context Protocol is the open standard Anthropic shipped for letting LLMs call external tools. An MCP server runs on your machine, exposes a set of tools over stdio (or sse), and the AI client calls them when the model decides to. WhatsApp MCP exposes 11 tools that map to common WhatsApp actions — search contacts, open a chat, read messages, send a message, navigate UI.
- Why not the WhatsApp Business Cloud API?
- The Business Cloud API is the right tool for high-volume opt-in messaging from a verified sender (support inboxes, drip campaigns). It is the wrong tool for the personal-account use case this MCP serves: assistants that read your DMs, send the occasional message on your behalf, or bridge WhatsApp into a larger agent. The Business API requires Meta dev account approval, opt-in template review, and a verified phone number; this server runs against your existing personal account in seconds.
- Why not WhatsApp Web automation?
- WhatsApp Web automation has two structural problems: the DOM and selectors change frequently, breaking scrapers; and the messaging protocol is end-to-end encrypted, so live message capture requires reverse-engineering the crypto. This server sidesteps both by driving the official native macOS app through accessibility APIs — a public, stable interface that the OS exposes for screen readers and assistive tech.
- Will my account get banned?
- The risk is materially lower than browser-automation tools because there is no protocol-level traffic for Meta to fingerprint as automated. The OS sees a human-pattern click and keystroke stream. That said: any automation carries some risk. Don't use this to blast hundreds of unsolicited DMs or run mass-marketing flows — that's what the Business API is for, and it's also what gets accounts flagged.
- Does it work on Linux or Windows?
- No. The server depends on macOS Accessibility APIs and the macOS Catalyst build of WhatsApp. There is no equivalent path on Linux or Windows because the WhatsApp desktop apps on those platforms are Electron wrappers around WhatsApp Web, not the same accessibility-rich Catalyst app.
- Which MCP clients work?
- Any MCP-compatible client that supports stdio transport. Tested with Claude Desktop, Claude Code (CLI), Cursor, Windsurf. It also works embedded inside larger agents like Fazm. The server is transport-agnostic Swift; nothing about it is Claude-specific.
- Does it read past messages?
- It reads what's currently visible in the WhatsApp UI, the same way you would by scrolling. It does not query the encrypted message database directly. For older history, the assistant can be instructed to scroll up before reading.
- Is it open source?
- Yes. MIT-licensed, full source on GitHub at github.com/m13v/whatsapp-mcp-macos. The npm package is a thin wrapper that compiles the Swift binary at install time.
- How do I uninstall?
- npm uninstall -g whatsapp-mcp-macos removes the package and the compiled binary. Then remove the mcpServers entry from your client config and revoke the host app's Accessibility permission if you want a clean state.
- Can I sponsor the project or contribute?
- Yes — issues and PRs welcome on GitHub. If you want a private feature or integration help, book a call from the link in the header.