WhatsApp MCP

Install

Works with Claude Code, Codex, VS Code, Cursor, Windsurf, Claude Desktop. Read the repository before you give any tool access to your data.

npx agentmarket install connector/adelaidasofia-whatsapp-mcp

About

No reviews yet. Installed it? Reviews come from verified installers only. How reviews work

Permissions

What this server can do and what it asks for, from its tool list, install config and code. Checked Oct 25, 2026.

Tools

6 read · 8 write · 0 delete

Secrets

1 (API keys, tokens or passwords)

Install scripts

None found

Runs as

Python package

Tools (14)

Read from the source code; the running server may differ. Descriptions are the server’s own words; hidden characters are shown as [U+…].

• confirm_send

  Commit a previously-drafted send. This is where the actual WhatsApp network send happens. Args: draft_id: The draft_id returned by a previous send_message call. Returns the final WhatsApp message ID on success. The sent message is also persisted into the local message database so it shows up in list_messages for the recipient chat. Errors: 404: draft not found 409: draft already confirmed/sent/failed (each draft can only be confirmed once) 410: draft expired (>1 hour since creation) 502: send failed at whatsmeow layer (bridge disconnected, invalid recipient, etc.)

• download_media

  Download and decrypt the media (image, document, video) attached to a message, saving it to disk under the bridge's media folder. Returns the LOCAL FILE PATH and mime type, NOT the bytes — read the path with a file tool. cached_hit is true if this message's media was already downloaded by an earlier call. Args: message_id: A message ID from list_messages — one with a media type (image/document/video) and no content_text.

• healthcheck

  Check the Go bridge is running and authenticated. Returns status, schema version, and feature flags. status_detail.auth_state explains pairing: "qr_pending" → the user must scan the QR (or POST /api/auth/pair-phone on the bridge for a typed code); "logged_out" → WhatsApp revoked the session and the bridge is already re-entering pairing; "paired" → healthy. Read tools also attach a _bridge_state envelope so cached data is distinguishable from live.

• list_chats

  List WhatsApp chats with metadata. Sorted by most recent message time. Args: limit: Max chats to return (default 20, max 200). offset: Pagination offset. unread_only: If true, return only chats with unread messages.

• list_messages

  List messages in a chat. Most recent first by default. Args: chat_jid: The JID of the chat (from list_chats or search_contacts). limit: Max messages (default 20, max 500). before: Return messages older than this message ID (pagination). include_crm_context: When true and WHATSAPP_VAULT_CRM_PATH is set, the response includes a `crm_context` block with the matching vault CRM note summary.

• mark_chat_read

  Mark one or more messages as read. Affects your WhatsApp unread count on this device AND across your linked devices. Low-consequence: no draft+confirm needed, this is a one-step call. Args: chat_jid: The chat to mark read. message_ids: List of message IDs to mark. Typically the IDs of the most recent unread messages for this chat.

• request_history

  Ask WhatsApp for OLDER messages in a chat than what auto-synced. This is a REAL, asynchronous request to WhatsApp's servers — not instant and not free of traffic. The response only confirms the request was SENT; older messages typically land within a few seconds and become visible via list_messages(chat_jid, before=<the chat's current oldest message id>) once they arrive — there is no separate "done" signal to poll. Media in the newly-arrived messages is metadata-only until download_media is called per message. Args: chat_jid: The chat or group JID to request older history for. count:…

• search_contacts

  Find contacts by name or phone number. Accent-insensitive. "Muñoz" matches "munoz", "José" matches "jose", "Zürich" matches "zurich".

• search_groups

  Find WhatsApp groups by name. Accent-insensitive, case-insensitive substring match. Unlike list_chats, this sees every JOINED group, not only ones with recent message history — list_chats only surfaces chats with traffic (often a few dozen), while a real account can belong to hundreds of groups with no recent activity. Participant phone numbers are NEVER returned by this tool. GET /api/groups includes every member's phone number for every group in the response; this tool strips that so a name lookup can't leak it. Use list_messages on the matched jid if you need to look inside the chat.

• send_message

  Create a DRAFT text message. Does NOT send until confirm_send is called. Returns a draft_id plus the resolved recipient display name, a preview, and an expires_at timestamp. Drafts expire after 1 hour. Each draft can be confirmed at most once. Args: recipient_jid: The recipient's WhatsApp JID (e.g. from list_chats or search_contacts). Must include the @s.whatsapp.net or @g.us suffix. text: The message text. No media / reactions / voice in v0.3.0. Two-step pattern rationale: prevents "replied to wrong person" disasters. Claude must show you the draft_id + recipient…

• send_reaction

  Create a DRAFT emoji reaction on a specific message. Args: recipient_jid: The chat JID where the target message lives. target_message_id: The ID of the message to react to. Find via list_messages. emoji: The reaction emoji (e.g., "❤️", "👍", "😂"). Pass "" to remove a previous reaction. Returns a draft_id. Call confirm_send(draft_id) to actually react.

• send_reply_quote

  Create a DRAFT reply-quote message that cites a specific earlier message. The recipient will see the original quoted message appear above your reply in their WhatsApp UI (the familiar reply-indicator format). Args: recipient_jid: The chat JID (direct or group). quoted_message_id: The ID of the message being quoted. Find it via list_messages. text: The reply text. Returns a draft_id. Call confirm_send(draft_id) to actually send.

• send_typing_indicator

  Show a "typing..." or "paused" indicator to the chat recipient. Args: chat_jid: The chat to signal. state: "composing" (typing) or "paused" (stopped typing). Default: composing. Useful as a courtesy signal right before calling confirm_send so the recipient sees "typing..." instead of the message appearing silently. Low-consequence.

• set_online_presence

  Signal your online/offline presence globally to all chats. Changing this affects your "last seen" visibility per WhatsApp's privacy settings. Args: online: True to appear online, False to appear offline.

Signals

Stars

6

Forks

10

Open issues

4

Weekly downloads

36

Last commit

Oct 15, 2026 (13 days ago)

Last release

Oct 7, 2026 (22 days ago)

Last package publish

May 20, 2026 (5 months ago)

From GitHub (fetched Oct 24, 2026) and the package registry.

Details

Registry name

io.github.adelaidasofia/whatsapp-mcp

Version

0.1.1

Auth

API key

Packages

pypi adelaidasofia-whatsapp-mcp

License

MIT

Repository

github.com/adelaidasofia/whatsapp-mcp

First seen

Oct 24, 2026

Last checked

Oct 25, 2026

Source

Official MCP Registrygithub-graphql