WhatsApp MCP Server

WhatsApp MCP Server

A single-binary Go MCP server that wraps whatsmeow to expose a personal WhatsApp account to LLMs. Your MCP client (Claude Desktop, Cursor, etc.) launches whatsapp-mcp serve over stdio on demand — no background daemon, no two-process bridge. Messages are cached in local SQLite and only travel to the model when the agent calls a tool.

Unaffiliated. This is an independent open-source project. It is not affiliated with, endorsed by, or otherwise associated with Meta Platforms, Inc., WhatsApp, or whatsmeow. "WhatsApp" is a trademark of Meta Platforms, Inc., used here nominatively to describe interoperability.

This started as a fork of lharries/whatsapp-mcp and has since been rewritten as a single Go binary. What it adds over the original:

• LID resolution — normalises @lid JIDs to real phone numbers for accurate contact matching.
• Sent-message storage — outgoing messages are persisted locally so conversation history stays complete.
• Disappearing-message timers — outgoing messages inherit the group chat's ephemeral timer automatically.
• Targeted history sync — on-demand per-chat backfill via the request_sync tool.
• Extended tool surface — 41 tools (see below): reactions, replies, edits, revoke, mark-read, typing, is-on-whatsapp, full group admin, blocklist, polls (create + vote + tally), contact cards, view-once flag, presence, privacy settings, and the profile "About" text.
• Single-instance enforcement — a flock(2) on store/.lock prevents two serve processes racing on the same SQLite files.

Setup

Prerequisites

• Go 1.25+ (build-time only; runtime needs just the compiled binary).
• An MCP client that speaks stdio (Claude Desktop, Cursor, etc.).
• FFmpeg (optional) — required only for send_audio_message when the input is not already .ogg Opus. Without it, use send_file to send raw audio.
• Windows: CGO must be enabled — see docs/windows.md.

Install

git clone https://github.com/Sealjay/mcp-whatsapp.git
cd mcp-whatsapp
make build    # writes ./bin/whatsapp-mcp

Pair your phone (first run only)

./bin/whatsapp-mcp login

Scan the QR code with WhatsApp on your phone (Settings → Linked Devices → Link a Device). The pairing persists to ./store/whatsapp.db. Re-run login only when WhatsApp invalidates the session or you want to switch accounts.

Connect your MCP client

whatsapp-mcp serve is an HTTP daemon on 127.0.0.1:8765 (or $WHATSAPP_MCP_ADDR). MCP clients connect to it over HTTP:

// Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "whatsapp": { "url": "http://127.0.0.1:8765/mcp" }
  }
}

// Claude Code — .claude/mcp.json (project) or ~/.claude/mcp.json (user)
{
  "mcpServers": {
    "whatsapp": { "type": "http", "url": "http://127.0.0.1:8765/mcp" }
  }
}

// Cursor — ~/.cursor/mcp.json
{
  "mcpServers": {
    "whatsapp": { "type": "http", "url": "http://127.0.0.1:8765/mcp" }
  }
}

Restart the client. WhatsApp appears as an available integration. Closing and reopening the client reconnects to the daemon — no process spawn, no per-session handshake, no stdin/stdout juggling.

Sending files

send_file and send_audio_message accept a media_path argument pointing at the file to send. By default, the path must live under ./store/uploads/ (resolved relative to your -store directory). On first run, serve creates the directory automatically; drop files you intend to send into it.

To allow a different directory, set WHATSAPP_MCP_MEDIA_ROOT (absolute path) in the MCP client's env block:

{
  "mcpServers": {
    "whatsapp": {
      "command": "{{PATH_TO_REPO}}/bin/whatsapp-mcp",
      "args": ["-store", "{{PATH_TO_REPO}}/store", "serve"],
      "env": { "WHATSAPP_MCP_MEDIA_ROOT": "/Users/me/whatsapp-outbox" }
    }
  }
}

Paths outside the allowed root are rejected with a clear error so Claude can ask you to move the file or update the env var. Symlinks inside the root are resolved before the check, so a symlink that points out of the root is also rejected. Do not place secrets inside the allowed root — the allowlist bounds what the tool can read, but anything inside is fair game.

Architecture

One binary, five internal packages:

cmd/whatsapp-mcp/       login / serve / smoke subcommands
internal/client/        whatsmeow client wrapper (send, download, events, history, features)
internal/store/         SQLite cache, LID resolution, query layer
internal/media/         ogg parsing, waveform synthesis, ffmpeg shell-out
internal/mcp/           mark3labs/mcp-go server + tool registrations

Process lifecycle

serve starts when the MCP client needs it and exits when the client disconnects. A flock(2) on store/.lock prevents two instances racing on the same store (WhatsApp would kick one of the two linked-device connections anyway).

The trade-off: events are persisted to SQLite only while serve is running. When the MCP client quits, the WhatsApp connection closes. On the next launch, whatsmeow emits events.HistorySync events that backfill conversations into SQLite, but the recovery window is governed by WhatsApp's server-side retention for multidevice clients — not by this codebase. Messages that arrive during a gap long enough to outlast WhatsApp's retention are not recoverable. For shorter, known gaps, the request_sync tool triggers a per-chat backfill on demand.

Data storage

Everything lives under ./store/ (override with -store DIR):

• store/messages.db — local chat/message cache, indexed for search.
• store/whatsapp.db — whatsmeow's own device/session state.
• store/.lock — ephemeral advisory lock for single-instance serve.

Data flow

1. The client sends a JSON-RPC tools/call to serve over stdio.
2. The MCP layer dispatches to an internal handler.
3. The handler either queries the local SQLite store or calls whatsmeow directly (send, download, reactions, etc.).
4. Incoming WhatsApp events are persisted to the store in a background goroutine inside the same process, so query tools always see current state.

Running the daemon

The daemon is designed to run independently of any MCP client. Three supported lifecycle models:

macOS — launchd. Template at docs/launchd/com.sealjay.whatsapp-mcp.plist. Copy to ~/Library/LaunchAgents/, replace {{PATH_TO_REPO}} / {{STORE_DIR}} placeholders, launchctl load. Daemon runs from login onwards.

Linux — systemd user unit. Template at docs/systemd/whatsapp-mcp.service. Copy to ~/.config/systemd/user/, replace placeholders, systemctl --user enable --now whatsapp-mcp.

Claude Code SessionStart hook. For project-scoped lifetimes, drop docs/hooks/setup.sh into your project's .claude/hooks/ and configure settings.json to invoke it. The hook is idempotent — safe to run alongside launchd/systemd.

Manual. ./bin/whatsapp-mcp serve -addr 127.0.0.1:8765 in any terminal. Ctrl-C to stop.

First-time pairing happens in a browser: start the daemon, open http://127.0.0.1:8765/pair, scan the QR with your phone. No terminal required. WhatsApp's multidevice protocol rotates the linked-device session roughly every 20 days; when that happens, the /pair page serves a fresh QR automatically — visit it again and re-pair.

Flags and environment variables for serve:

• -addr host:port (env WHATSAPP_MCP_ADDR, default 127.0.0.1:8765).
• -allow-remote (explicit opt-in to bind a non-loopback address).
• WHATSAPP_MCP_MEDIA_ROOT — allowed root for send_file / send_audio_message paths.
• WHATSAPP_MCP_DEBUG=1 — disable JID/body redaction in logs.

Tools

41 tools, grouped by purpose.

Read / query

Send

Message actions

Groups

Blocklist

Privacy / presence / status

Admin

Deferred

Intentionally not exposed yet:

• subscribe_presence — no persistence layer for presence events, skipped to avoid a dangling tool.
• Profile photo setter — upstream whatsmeow doesn't expose a user-level setter.
• Approval-mode participants, communities, newsletters — low-use surface, deferred.

Limitations

• Prompt-injection risk: as with many MCP servers, this one is subject to the lethal trifecta. Prompt injection in incoming messages could lead to private data exfiltration — treat the tool surface accordingly.
• Re-authentication: WhatsApp may invalidate the linked-device session periodically; re-run ./bin/whatsapp-mcp login when that happens.
• Message gaps when serve isn't running: events only flow into SQLite while the binary is alive. Messages sent during an offline window are recovered on next reconnect only if WhatsApp's multidevice retention still holds them; for longer gaps use request_sync per chat, or accept the loss.
• Single instance per store: only one whatsapp-mcp serve can hold the store lock. Parallel MCP clients must point at different -store directories (and therefore different paired sessions).
• Windows: requires CGO and a C compiler — see docs/windows.md.
• Upstream bounds: message fetch/send is bounded by what whatsmeow supports against the WhatsApp web multidevice API.
• Log redaction is obfuscation, not anonymisation. Partial knowledge of your contacts allows correlation from …last4. Symlinks inside ./store/uploads/ are resolved before the path check so they cannot escape, but the root itself is a trust boundary — only place files you intend to send inside it.

Development

make test          # unit tests
make test-race     # with -race
make vet           # go vet
make e2e           # build + JSON-RPC smoke over stdio (requires -tags=e2e)
make smoke         # boot-test the server without connecting to WhatsApp

Upgrading whatsmeow

Weekly CI runs an upstream upgrade probe. To do it manually:

make upgrade-check

This bumps go.mau.fi/whatsmeow@main, re-tidies, builds, and tests. If green, commit the go.mod / go.sum changes.

scripts/mdtest-parity.sh in CI fails the build early if upstream removes or renames any whatsmeow method we call — it's the canary for API drift.

Troubleshooting

• connect failed … on serve — run ./bin/whatsapp-mcp login first. serve cannot display a QR because its stdout is reserved for MCP JSON-RPC.
• another whatsapp-mcp instance is already running — only one serve can hold the store lock. Check for a stray process (ps aux | grep whatsapp-mcp) or another MCP client pointed at the same -store directory.
• QR doesn't display — the terminal doesn't render half-block Unicode. Try iTerm2, Windows Terminal, or similar.
• Device limit reached — WhatsApp caps linked devices. Remove one from Settings → Linked Devices on your phone.
• No messages loading — after initial auth, it can take several minutes for history to backfill. Use request_sync to target a specific chat.
• WhatsApp out of sync — delete both database files (store/messages.db and store/whatsapp.db) and re-run login.
• ffmpeg not found — send_audio_message needs ffmpeg on PATH to convert non-Opus audio. Use send_file for raw audio instead.

Debug logging

By default, JIDs in stderr logs are redacted to …<last-4-chars-of-user-part> and message bodies are summarised as [<length>B: text|url|command]. To see full content while actively debugging:

• As a flag: ./bin/whatsapp-mcp -debug serve

• As an env var in your MCP client config:

  "env": { "WHATSAPP_MCP_DEBUG": "1" }
  

Turn it back off once you're done — redaction is there so shared log snippets don't leak conversation content.

Honesty disclaimer. The …last4 scheme is obfuscation for log-reader convenience, not anonymisation. Someone with independent knowledge of your contacts can still correlate …4567 with a specific phone number. Treat redacted logs as "probably safe to paste into a GitHub issue", not "anonymised".

For Claude Desktop integration issues, see the MCP documentation.

Contributing

Contributions welcome via pull request. See CONTRIBUTING.md.

Licence

MIT Licence — see LICENSE.