Skip to main content
Glama
wa-bridge-mcp

wa-bridge-mcp

by yehudashtein

wa-bridge-mcp

A small Model Context Protocol (MCP) server that lets an AI assistant (Claude Desktop, Claude Code, etc.) read and send WhatsApp messages through the api-supp WhatsApp bridge.

It's an HTTP client only — every operation goes through the bridge's REST API, so there's no local database, no QR pairing here, and nothing sensitive stored on your machine. You authenticate with a tenant token that scopes the MCP to your own WhatsApp account.

This is a fork of lharries/whatsapp-mcp (MIT), re-worked to talk to a hosted bridge over HTTP. See NOTICE.

What you need

  • Python 3.11+ (and uv recommended)

  • Your bridge URL (default https://api.api-supp.com/v1) and a tenant token (wat_…) — provided to you during onboarding.

Related MCP server: WSAPI WhatsApp MCP Server

Install

git clone https://github.com/yehudashtein/wa-bridge-mcp.git
cd wa-bridge-mcp
uv sync        # or: pip install -e .

Configure

The MCP reads its settings from environment variables:

Variable

Required

Default

Notes

WHATSAPP_BRIDGE_TOKEN

✅

—

Your tenant bearer (wat_…) — keep it secret

WHATSAPP_BRIDGE_URL

—

https://api.api-supp.com/v1

Bridge base URL (include /v1)

WHATSAPP_HTTP_TIMEOUT

—

30

Per-request timeout (seconds)

Copy .env.example → .env for local runs, or set them in your MCP client config.

Claude Desktop / Claude Code

Add to your MCP config (e.g. claude_desktop_config.json or .claude.json):

{
  "mcpServers": {
    "whatsapp": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/wa-bridge-mcp", "run", "main.py"],
      "env": {
        "WHATSAPP_BRIDGE_URL": "https://api.api-supp.com/v1",
        "WHATSAPP_BRIDGE_TOKEN": "wat_your_tenant_token_here"
      }
    }
  }
}

Restart the client and the WhatsApp tools appear.

Tools

Tool

What it does

search_contacts

Search your contacts by name or number

list_chats

List chats (with last message)

get_chat / get_contact_chats / get_direct_chat_by_contact

Look up chats

list_messages

Read messages with filters (chat, time, sender, media, …)

get_message_context

Messages around a specific one

get_last_interaction

Most recent message with a contact

send_message

Send a text message

send_file / send_audio_message

Send media / voice notes

download_media

Download media from a message

sync_history

Ask the bridge to re-sync history

Notes

  • The token scopes you to your own WhatsApp account; it can't see other users' data.

  • Non-ASCII text (Hebrew/Arabic/emoji) sends fine — the bridge handles encoding.

  • Nothing is stored locally; the MCP is a thin HTTP client.

License

MIT — see LICENSE and NOTICE (derivative of lharries/whatsapp-mcp).

Available Tools

13 tools
download_mediaCInspect

Download media from a WhatsApp message and get the local file path.

Args:
    message_id: The ID of the message containing the media
    chat_jid: The JID of the chat containing the message

Returns:
    A dictionary containing success status, a status message, and the file path if successful

Inputs: chat_jid (required), message_id (required).

get_chatBInspect

Get WhatsApp chat metadata by JID.

Args:
    chat_jid: The JID of the chat to retrieve
    include_last_message: Whether to include the last message (default True)

Inputs: chat_jid (required), include_last_message.

get_contact_chatsBInspect

Get all WhatsApp chats involving the contact.

Args:
    jid: The contact's JID to search for
    limit: Maximum number of chats to return (default 20)
    page: Page number for pagination (default 0)

Inputs: jid (required), page, limit.

get_direct_chat_by_contactCInspect

Get WhatsApp chat metadata by sender phone number.

Args:
    sender_phone_number: The phone number to search for

Inputs: sender_phone_number (required).

get_last_interactionCInspect

Get most recent WhatsApp message involving the contact.

Args:
    jid: The JID of the contact to search for

Inputs: jid (required).

get_message_contextAInspect

Get context around a specific WhatsApp message.

Args:
    message_id: The ID of the message to get context for
    before: Number of messages to include before the target message (default 5)
    after: Number of messages to include after the target message (default 5)

Inputs: message_id (required), after, before.

list_chatsAInspect

Get WhatsApp chats matching specified criteria.

Args:
    query: Optional search term to filter chats by name or JID
    limit: Maximum number of chats to return (default 20)
    page: Page number for pagination (default 0)
    include_last_message: Whether to include the last message in each chat (default True)
    sort_by: Field to sort results by, either "last_active" or "name" (default "last_active")

Inputs: page, limit, query, sort_by, +1 more.

list_messagesBInspect

Get WhatsApp messages matching specified criteria with optional context.

Args:
    after: Optional ISO-8601 formatted string to only return messages after this date
    before: Optional ISO-8601 formatted string to only return messages before this date
    sender_phone_number: Optional phone number to filter messages by sender
    chat_jid: Optional chat JID to filter messages by chat
    query: Optional search term to filter messages by content
    limit: Maximum number of messages to return (default 20)
    page: Page number for pagination (default 0)
    include_context: Whether to include messages before and after matches (default True)
    context_before: Number of messages to include before each match (default 1)
    context_after: Number of messages to include after each match (default 1)
    include_groups: Whether to include group chat messages (default False)

Inputs: page, after, limit, query, +7 more.

search_contactsCInspect

Search WhatsApp contacts by name or phone number.

Args:
    query: Search term to match against contact names or phone numbers

Inputs: query (required).

send_audio_messageAInspect

Send any audio file as a WhatsApp audio message to the specified recipient. For group messages use the JID. If it errors due to ffmpeg not being installed, use send_file instead.

Args:
    recipient: The recipient - either a phone number with country code but no + or other symbols,
             or a JID (e.g., "123456789@s.whatsapp.net" or a group JID like "123456789@g.us")
    media_path: The absolute path to the audio file to send (will be converted to Opus .ogg if it's not a .ogg file)

Returns:
    A dictionary containing success status and a status message

Inputs: recipient (required), media_path (required).

send_fileBInspect

Send a file such as a picture, raw audio, video or document via WhatsApp to the specified recipient. For group messages use the JID.

Args:
    recipient: The recipient - either a phone number with country code but no + or other symbols,
             or a JID (e.g., "123456789@s.whatsapp.net" or a group JID like "123456789@g.us")
    media_path: The absolute path to the media file to send (image, video, document)

Returns:
    A dictionary containing success status and a status message

Inputs: recipient (required), media_path (required).

send_messageAInspect

Send a WhatsApp message to a person or group. For group chats use the JID.

Args:
    recipient: The recipient - either a phone number with country code but no + or other symbols,
             or a JID (e.g., "123456789@s.whatsapp.net" or a group JID like "123456789@g.us")
    message: The message text to send

Returns:
    A dictionary containing success status and a status message

Inputs: message (required), recipient (required).

sync_historyAInspect

Trigger a WhatsApp history sync to fetch missed messages from the server. Use this when messages appear to be missing or after a bridge restart.

Returns:
    A dictionary containing success status and a status message

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 13 tools

    Disambiguation3/5

    Most tools are distinct, but the read side has several overlapping lookups: get_chat vs. get_direct_chat_by_contact, get_last_interaction vs. list_messages (limit 1 filtered by contact), and get_message_context vs. list_messages with include_context all return similar data via different entry points. send_audio_message vs. send_file also overlap, though the description explicitly disambiguates them.

    Naming Consistency4/5

    All tools use snake_case with a verb_noun structure (search_contacts, list_messages, send_file, get_message_context), which is predictable and readable. Minor irregularity from compound names like get_direct_chat_by_contact, but the convention holds throughout.

    Tool Count4/5

    13 tools is a well-scoped count for a WhatsApp bridge covering read, send, media, and sync workflows. Slightly lean toward redundant read helpers (get_direct_chat_by_contact could fold into get_chat), but nothing is gratuitous.

    Completeness4/5

    Core lifecycle is covered: contacts, chats, messages, context, media download, history sync, and sending text/file/audio. Gaps exist for message deletion, forwarding, reactions, and read receipts, which agents may need but can work around.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to interact with your personal WhatsApp account, allowing them to search messages and contacts, retrieve chat history, and send messages to individuals or groups. Uses WhatsApp Web API with local data storage for privacy and security.
      ISC
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to interact with WhatsApp through the WSAPI service, supporting comprehensive messaging, contact management, group operations, and account management functionality. Allows sending various media types, managing chats, and controlling WhatsApp sessions through natural language.
      101
      20 npm
      4
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to interact with WhatsApp through the WAHA (WhatsApp HTTP API) platform. Supports chat management, message operations including sending/receiving messages, and marking chats as read.
      52
      11
      ISC