Repository avatar
Other Tools
v0.2.0
active

whatsapp-mcp

io.github.muhammedanasmithadi/whatsapp-mcp

Self-hosted personal WhatsApp bridge with 86 MCP tools over stdio or Streamable HTTP.

Documentation

WhatsApp MCP

A self-hosted Model Context Protocol (MCP) server that gives an AI agent read and send access to your personal WhatsApp account. It runs on your machine as a single Go binary, speaks MCP over Streamable HTTP at 127.0.0.1:8765/mcp, and keeps your message history in a local SQLite database.

This is an independent, community project. It is not affiliated with, endorsed by, or operated by Meta Platforms, Inc. or WhatsApp LLC.

What it does

Once paired with your phone (the same way you link WhatsApp Web), the daemon:

DomainWhat it does
MessagesRead, search, send, edit, delete, and recover messages; read receipts; mark read; schedule messages; reply; react; poll; contact cards; locations; voice-note transcription
Statuses (Stories)Read, view, post, delete statuses; read receipts; status privacy setting
ProfileRead/set About text, profile photo, contact metadata (About, verified name, LID, linked devices)
PresenceQuery contact online/last-seen; set per-chat typing/recording indicators
GroupsCreate, leave, join via link, participants, name, topic, announce, lock, invite link
ChannelsFollow/unfollow, mute, list, info, messages
ContactsLocal address book (bridge-only; not synced to the phone), search, create, update, delete
Blocklist & PrivacyBlocklist, privacy settings (group add, last seen, status, profile, read receipts, online, calls, messages, defense, stickers)
SchedulingTimer-driven scheduled messages that survive restarts
Auto-responderEvent-driven out-of-office replies to incoming 1:1 text messages
Audit & observabilityAudit log, health check, Prometheus metrics, WebSocket events, SSE pairing events

The daemon exposes 86 MCP tools over Streamable HTTP, serves health (/healthz) and Prometheus metrics (/metrics), and pushes new messages to connected clients over WebSocket (/ws/events).

Architecture

┌─────────────────┐      Streamable HTTP      ┌─────────────────────┐
│   AI agent      │◄─────────────────────────►│  whatsapp-mcp       │
│  (Claude, etc.) │      /mcp                 │  MCP server (Go)    │
└─────────────────┘                           │  • 86 tool handlers   │
                                              │  • rate limiting      │
                                              │  • SQLite cache       │
                                              └──────────┬──────────┘
                                                         │
                                                         │ whatsmeow multidevice
                                                         │ protocol (vendored fork)
                                                         ▼
                                              ┌─────────────────────┐
                                              │  WhatsApp Web         │
                                              │  (linked device)      │
                                              │  phone ↔ server       │
                                              └─────────────────────┘

The daemon wraps whatsmeow, the Go WhatsApp Web multidevice library. Because WhatsApp changes its protocol server-side without notice, the project vendors whatsmeow via a Go replace directive and applies protocol fixes immediately rather than waiting for upstream:

replace go.mau.fi/whatsmeow => ./vendor-whatsmeow/go.mau.fi/whatsmeow

Protocol fixes carried in the fork (also contributed upstream where applicable):

FixWhat it does
SKDM group IDhandleSenderKeyDistributionMessage uses the protobuf groupId, not the enclosing stanza chat, to decide sender-key ownership. This makes statuses and group messages decrypt correctly when retried as direct-to-device SKDMs. Upstream: tulir/whatsmeow#1330
Profile picture tctokenMedia requests include the required token so thumbnails resolve
Presence subscribeMissing id attribute added to presence subscription stanzas
Argo decodingHard-coded failure and macOS early-return removed
SendPresence racePresence updates no longer race with session teardown
GetPrivacySettingsErrors are no longer swallowed
set_status_messageWhatsApp Web calls the xwa2_update_text_status MEX mutation (ID 9152604461510864) first, then the legacy <iq xmlns="status"> stanza. The MEX mutation is account-gated and fails with a 400 CRITICAL error on accounts without the text-status feature, so it is sent only when an emoji or ephemeral duration is requested; the legacy IQ is always sent
canonicalContactJIDWrong suffix @s.client.net → @s.whatsapp.net fixed

Quick start

Prerequisites

  • Go 1.26+ (build-time only; runtime needs just the compiled binary)
  • FFmpeg (optional, for voice-note transcoding via send_audio_message)
  • An MCP client that speaks HTTP (Claude Desktop, Cursor, Claude Code, OpenCode, etc.)

Build

Download a prebuilt binary from the latest release. Release assets cover Linux (amd64, arm64), macOS (amd64, arm64) and Windows (amd64), with SHA-256 sums in checksums.txt. The binary needs no runtime dependencies except FFmpeg for voice-note transcoding.

Or build from source:

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

Pair your phone

Start the daemon, then open the pairing page:

./bin/whatsapp-mcp serve          # starts on 127.0.0.1:8765

Visit http://127.0.0.1:8765/pair, scan the QR code with WhatsApp (Settings → Linked Devices → Link a Device), and the session persists to ./store/whatsapp.db. WhatsApp rotates the session roughly every 20 days; the daemon re-pairs automatically with exponential backoff.

No browser? Run ./bin/whatsapp-mcp login to render the QR in the terminal, or use the phone-number form on /pair.

Connect your MCP client

Add this to your client configuration:

// OpenCode (opencode.jsonc), Claude Code, Cursor, etc.
{
  "mcpServers": {
    "whatsapp": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

Restart your client. The daemon outlives client restarts.

One-click install with MCPB

Each release also ships a .mcpb bundle for Linux, macOS and Windows. Install the bundle matching your platform in an MCPB-capable desktop client; the client starts the binary over stdio and fills in the configuration for you.

Pair once before installing the bundle, because stdio mode has no browser to show a QR code:

whatsapp-mcp -store ~/.whatsapp-mcp login

The bundle's store_dir setting defaults to ~/.whatsapp-mcp, and its read_only setting maps to WHATSAPP_MCP_READ_ONLY. To run stdio mode by hand:

whatsapp-mcp -store ~/.whatsapp-mcp stdio -read-only

stdout carries JSON-RPC frames only; every diagnostic goes to stderr.

Serve flags and environment

Flag / env varDefaultPurpose
-addr / WHATSAPP_MCP_ADDR127.0.0.1:8765HTTP bind address
-allow-remoteoffBind to a non-loopback address (requires WHATSAPP_MCP_TOKEN)
WHATSAPP_MCP_TOKEN—Bearer token for /mcp and /pair/* when remote-bound
-read-only / WHATSAPP_MCP_READ_ONLYoffExpose only read/query tools (no send, edit, delete, mark-read, group, blocklist, privacy, status-change tools)
-log-format / WHATSAPP_MCP_LOG_FORMATtexttext for human logs; json for structured JSON lines
WHATSAPP_MCP_MEDIA_ROOT<store>/uploads/File allowlist root for send/download tools
WHATSAPP_MCP_DEVICE_NAMEWhatsApp MCPName shown for this device in WhatsApp → Linked Devices
WHATSAPP_MCP_FULL_HISTORY_SYNCoffBackfill older messages for all cached chats after pairing
-debug / WHATSAPP_MCP_DEBUGoffVerbose (unredacted) logs

Observability

  • GET /healthz — JSON: connected, paired, state, uptime_sec
  • GET /metrics — Prometheus text format: messages in/out, sends, errors, rate-limited, pairing state, uptime

Real-time push

  • WS /ws/events — WebSocket broadcast of new-message events as JSON
  • GET /pair/events — Server-Sent Events stream of pairing state transitions

MCP tools reference

The server exposes 86 tools, grouped by domain:

Messaging

ToolDescription
send_messageSend a text message to a person or group
send_fileUpload and send a picture, video, document, or attachment
send_audio_messageSend an audio file as a voice note (transcodes via ffmpeg if needed)
send_locationSend a map location
send_contact_cardSend a contact card (vCard)
send_pollSend a poll with 2–32 options
send_poll_voteCast a vote on a poll
send_reactionAdd or replace an emoji reaction on a message
send_replySend a reply that quotes a previous message
edit_messageEdit the text of a sent message
delete_messageRevoke (delete) a sent message
recover_mediaRequest WhatsApp to re-send media for a message
transcribe_voice_noteTranscribe a voice note via the configured STT endpoint
batch_send_messagesSend multiple messages in one call

Statuses (Stories)

ToolDescription
list_status_updatesList cached Status updates grouped by sender
mark_status_viewedSend read receipts for a contact's statuses
send_statusPost a Status update (image/video + caption)
delete_statusDelete one of your own status updates
get_status_viewersViewers of a status (WhatsApp does not expose this to linked devices; returns empty list with a note)
set_status_privacy_settingSet who can see your statuses (all, contacts, close_friends, custom)

Profile & presence

ToolDescription
get_contact_infoLive profile metadata (About, profile-picture ID, LID, devices, business verification)
get_profile_pictureFetch a contact's or group's profile photo
set_profile_pictureSet the paired account's profile photo
set_status_messageSet the About text shown in the profile
get_presenceQuery a contact's online/last-seen state
send_typingShow or hide per-chat typing/recording indicator
send_presenceSet global online/offline availability

Groups

ToolDescription
create_groupCreate a group with participants
leave_groupLeave a group
join_group_with_linkJoin a group via invite link
get_group_infoGet group metadata
get_group_invite_linkGet or reset a group invite link
set_group_nameRename a group
set_group_topicSet group topic/description
set_group_announceSet announce-only mode
set_group_lockedLock/unlock a group
update_group_participantsAdd/remove/promote/demote participants
mute_chatMute/unmute a chat
pin_chatPin/unpin a chat in the chat list

Channels

ToolDescription
list_channelsList followed WhatsApp Channels
follow_channelFollow a channel
unfollow_channelUnfollow a channel
mute_channelMute/unmute a channel
get_channel_infoGet channel metadata
list_channel_messagesList messages from a channel

Contacts

ToolDescription
list_contactsList local address-book contacts
create_contactCreate a local contact entry
update_contactUpdate a local contact
delete_contactDelete a local contact
search_contactsSearch contacts by name or phone
is_on_whatsappCheck if phone numbers are registered on WhatsApp

Blocklist & privacy

ToolDescription
get_blocklistList blocked contacts
block_contactBlock a contact
unblock_contactUnblock a contact
get_privacy_settingsRead privacy settings
set_privacy_settingSet a privacy setting (group_add, last, status, profile, read_receipts, online, call_add, messages, defense, stickers)

Scheduling

ToolDescription
schedule_messageQueue a text message for later delivery (timer-driven, survives restarts)
cancel_scheduled_messageCancel a pending scheduled message
list_scheduled_messagesList queued messages with status

Auto-responder

ToolDescription
set_auto_responderEnable/disable automatic replies to incoming 1:1 text messages
get_auto_responderRead current auto-responder configuration

Chat management

ToolDescription
mute_chatMute/unmute a chat
pin_chatPin/unpin a chat
archive_chatArchive/unarchive a chat
set_disappearing_timerSet disappearing-message timer
star_messageStar/unstar a message

History & queries

ToolDescription
list_chatsList cached chats
list_messagesList messages in a chat
list_chats_by_labelList chats by label
get_message_contextGet context around a message
get_chatGet chat metadata
list_media_messagesList messages with media
download_mediaDownload media for a message
search_contactsSearch contacts
get_read_position / set_read_positionRead/set read position in a chat
mark_chat_read / mark_readMark messages as read
mark_read_positionMark read position

Pairing & audit

ToolDescription
pairing_statusReturn pairing state
get_audit_logReturn audit-log entries

Statuses (Stories) — push-only delivery, recoverable via re-pair

Status updates arrive as push broadcasts while the daemon is online and paired. There is no on-demand server fetch for statuses on an already-paired device — WAWebApiStatus.getAllStatuses reads from local cache only.

Missing statuses can be recovered by re-pairing. When a linked device pairs for the first time, WhatsApp sends INITIAL_STATUS_V3 (history sync type 1) which carries recent status updates. The daemon imports HistorySync.statusV3Messages (field 3) into status@broadcast rows, resolves the poster via key.participant / WebMessageInfo.participant (LID → phone number), and keeps placeholders for pruned payloads.

To recover statuses posted while the daemon was offline:

  1. Log out the MCP device from your phone (WhatsApp → Linked Devices → "WhatsApp MCP" → Log out)
  2. Restart the daemon: systemctl --user restart whatsapp-mcp.service
  3. Scan the fresh QR code at http://127.0.0.1:8765/pair
  4. During pairing bootstrap, WhatsApp sends INITIAL_STATUS_V3 and the daemon caches recent statuses automatically

Profile photos and online/last-seen presence work independently of status delivery.

Safety

This tool connects an AI agent to your personal WhatsApp account. Treat it accordingly:

  • Loopback only by default. The daemon binds to 127.0.0.1. Do not expose it remotely without WHATSAPP_MCP_TOKEN.
  • Read-only mode. Run with -read-only if you only need the agent to read and summarize chats. It strips every send, edit, delete, mark-read, group, blocklist, privacy, and status-change tool.
  • Untrusted input. Incoming message text is data fed to an LLM. Prompt injection could exfiltrate chat history. Do not assume message content is safe.
  • Contacts did not consent. Their messages to you enter the agent's context window and go to the model provider.

Media

WHATSAPP_MCP_MEDIA_ROOT (default <store>/uploads/) is the only directory send/download tools may touch. Paths outside the root, including symlinks that resolve outside it, are rejected.

Operations

systemd (Linux)

The project includes a systemd user unit at docs/systemd/whatsapp-mcp.service. Install it:

mkdir -p ~/.config/systemd/user
cp docs/systemd/whatsapp-mcp.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now whatsapp-mcp.service

launchd (macOS)

A launchd plist is provided at docs/launchd/com.sealjay.whatsapp-mcp.plist.

Webhooks

The daemon optionally verifies /webhook/ signatures using WHATSAPP_WEBHOOK_SECRET.

Development

make build        # writes ./bin/whatsapp-mcp
make test         # unit tests
make test-race    # with -race
make test-cover   # coverage report
make vet          # go vet
make fmt          # gofmt check
make lint         # vet + fmt
make smoke        # boot-test without connecting to WhatsApp
make e2e          # end-to-end tests (requires paired daemon)
make upgrade-check # bump go.mau.fi/whatsmeow, re-tidy, build, test

Pair for integration testing

./bin/whatsapp-mcp login

There is no offline fixture for whatsmeow sessions; integration testing requires a real paired WhatsApp account.

Contributing

  • Open an issue before starting non-trivial work so we can agree on scope.
  • One logical change per pull request. Keep diffs focused and reviewable.
  • Match existing code style in Go (cmd/, internal/).
  • Do not commit .env files, database files (*.db), session state, or media.
  • Do not re-add .claude/ or docs/superpowers/ — those were removed from the repo.
  • If you add a new tool, update expectedToolNames and the tool count in internal/mcp/tools_test.go.
  • If you add a new env var or serve flag, document it in README.md under "Serve flags and environment".

License

MIT. See LICENSE.

MCPB
https://github.com/muhammedanasmithadi/whatsapp-mcp/releases/download/v0.2.0/whatsapp-mcp_0.2.0_darwin_amd64.mcpb
Install Command
# mcpb: https://github.com/muhammedanasmithadi/whatsapp-mcp/releases/download/v0.2.0/whatsapp-mcp_0.2.0_darwin_amd64.mcpb
MCPB
https://github.com/muhammedanasmithadi/whatsapp-mcp/releases/download/v0.2.0/whatsapp-mcp_0.2.0_darwin_arm64.mcpb
Install Command
# mcpb: https://github.com/muhammedanasmithadi/whatsapp-mcp/releases/download/v0.2.0/whatsapp-mcp_0.2.0_darwin_arm64.mcpb
MCPB
https://github.com/muhammedanasmithadi/whatsapp-mcp/releases/download/v0.2.0/whatsapp-mcp_0.2.0_linux_amd64.mcpb
Install Command
# mcpb: https://github.com/muhammedanasmithadi/whatsapp-mcp/releases/download/v0.2.0/whatsapp-mcp_0.2.0_linux_amd64.mcpb
MCPB
https://github.com/muhammedanasmithadi/whatsapp-mcp/releases/download/v0.2.0/whatsapp-mcp_0.2.0_linux_arm64.mcpb
Install Command
# mcpb: https://github.com/muhammedanasmithadi/whatsapp-mcp/releases/download/v0.2.0/whatsapp-mcp_0.2.0_linux_arm64.mcpb
MCPB
https://github.com/muhammedanasmithadi/whatsapp-mcp/releases/download/v0.2.0/whatsapp-mcp_0.2.0_windows_amd64.mcpb
Install Command
# mcpb: https://github.com/muhammedanasmithadi/whatsapp-mcp/releases/download/v0.2.0/whatsapp-mcp_0.2.0_windows_amd64.mcpb