wa-bridge-mcp
Allows reading and sending WhatsApp messages through a hosted bridge, including searching contacts, listing chats and messages, retrieving message context and last interactions, sending text messages, files and audio messages, downloading media, and syncing history.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@wa-bridge-mcp send a WhatsApp to Mom saying I'll be home by 7"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
uvrecommended)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 |
| ✅ | — | Your tenant bearer ( |
| — |
| Bridge base URL (include |
| — |
| 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 your contacts by name or number |
| List chats (with last message) |
| Look up chats |
| Read messages with filters (chat, time, sender, media, …) |
| Messages around a specific one |
| Most recent message with a contact |
| Send a text message |
| Send media / voice notes |
| Download media from a message |
| 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 toolsdownload_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
Scored across 13 tools
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.
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.
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.
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
Read, summarize and send your own WhatsApp messages from AI assistants (OAuth 2.1).
WhatsApp for Claude, ChatGPT or any AI agent: search, reply and send. Personal or Business API.
WhatsApp CRM for AI agents: search contacts, read chats, manage the sales pipeline, send messages.
Send WhatsApp messages and templates, manage chats, contacts, broadcasts and AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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
- AlicenseAqualityBmaintenanceEnables 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.10120 npm4MIT
- AlicenseBqualityDmaintenanceEnables 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.5211ISC

GoWA MCP Serverofficial
AlicenseNot gradedqualityBmaintenanceEnables AI agents and tools to send and manage WhatsApp messages, media, statuses, and scheduled sends across multiple linked devices.MIT