Loading...
How WhatsApp MCP — Hebrew-Compatible Fork works
The Go bridge uses whatsmeow to authenticate with WhatsApp Web via QR code scan. Messages are stored in a local SQLite database. A REST API on port 8741 (personal) or 8742 (business) exposes send operations. The bridge runs as a long-lived process that maintains the WhatsApp Web session.
WhatsApp Web
QR auth
whatsmeow
Go client library
SQLite
Message store
REST API
Port 8741/8742
WhatsApp Web
QR auth
whatsmeow
Go client library
SQLite
Message store
REST API
Port 8741/8742
SQLite's built-in LOWER() function only handles ASCII characters (A-Z → a-z). For Hebrew, Arabic, emoji, and CJK text, LOWER() is a no-op — the text passes through unchanged. The upstream repo's LOWER(column) LIKE LOWER(?) pattern silently fails for non-Latin scripts. Our fork replaces this with instr()-based matching: a dual check that handles both case-insensitive Latin and direct Unicode byte-level matching.
# Upstream (broken for Hebrew/Arabic/CJK):
WHERE LOWER(chats.name) LIKE LOWER(?)
# → LOWER("שלום") returns "שלום" unchanged
# → LIKE "%שלום%" may fail on substring match
# Our fork (works for all Unicode):
WHERE instr(LOWER(chats.name), LOWER(?)) > 0
OR instr(chats.name, ?) > 0
# → instr() does byte-level substring matching
# → Dual check: case-insensitive Latin + direct UnicodeApplied to list_chats, list_messages, and search_contacts
SQLite can load the ICU extension for proper Unicode collation, but it requires a C library dependency and isn't available in all environments. instr() is built-in, zero-dependency, and works everywhere SQLite runs.
The Python MCP server checks for a business bridge database at whatsapp-bridge-business/store/messages.db. If it exists, it connects to the business bridge. Otherwise it falls back to the personal bridge at whatsapp-bridge/store/messages.db. Environment variables WHATSAPP_DB_PATH and WHATSAPP_API_URL override auto-detection for custom setups.
Personal Bridge
Port 8741
Business Bridge
Port 8742
Auto-Detect
Check file existence
SQLite DB
Shared schema
Python MCP
12 tools
Personal Bridge
Port 8741
Business Bridge
Port 8742
Auto-Detect
Check file existence
SQLite DB
Shared schema
Python MCP
12 tools
12 tools split into query (9) and mutation (3) categories. Query tools cover every read pattern: search contacts by name or phone, list messages with filters (chat, sender, date range, content), get chat metadata, fetch message context around a specific message, and download media (images, videos, audio). Mutation tools handle sending: text messages, files with captions, and voice messages with automatic Opus/OGG conversion via FFmpeg.
search_contactsUnicode-safe name + phone searchlist_messagesFilter by chat, sender, date, contentlist_chatsAll chats with optional last-message previewget_chatChat metadata by JIDget_direct_chat_by_contactFind DM chat for a contactget_contact_chatsAll chats involving a contactget_last_interactionMost recent message with a contactget_message_contextMessages around a specific message IDdownload_mediaImages, videos, audio from messagessend_messageText message to a JIDsend_fileFile with optional captionsend_audio_messageVoice message with FFmpeg Opus conversionWhen WHATSAPP_OWNER_JID is set, all send operations (send_message, send_file, send_audio_message) are restricted to the owner's JID — effectively a 'Saved Messages' mode. Read operations remain unrestricted, so Claude can search and reference any conversation. Phone numbers are normalized: leading '+' stripped, whitespace removed, @s.whatsapp.net appended.
Letting an LLM send messages to arbitrary contacts is dangerous. Self-chat mode lets Claude use WhatsApp as a note-taking and reference tool without risk of accidentally messaging people. Read everything, send only to yourself.