Summary

A personal WhatsApp account an agent can read and write — with the terms-of-service question that comes attached.

This drives WhatsApp Web through a browser rather than Meta's Business API, and the repository opens by saying that automating WhatsApp this way is against WhatsApp's terms and can get an account flagged or restricted. What it covers is complete for a personal account: contacts, chat history, media in both directions, and a linked session that survives restarts. One thing to know when reading results — list_chats and get_last_interaction return the newest event of any type, so a call log can read like a message; list_messages is the call that answers what someone actually said.

What it is

A TypeScript server that drives WhatsApp Web in a browser using your own account. Once the device is linked it searches contacts, lists chats, reads message history, sends text and media, and downloads attachments.

What you get

Linking handled in-band: get_qr_code returns the QR as an image result, request_pairing_code returns an 8-character code to type on the phone instead, check_auth_status reports whether the session is live and logout clears it
search_contacts by name or phone number, and get_contact_by_id when you already hold the JID
list_chats sorted by recent activity, get_chat_by_id for metadata, and get_direct_chat_by_contact_number to turn a phone number into a chat
list_messages returns what was actually said in a chat; get_message_by_id fetches a single message and get_message_context the ones around it
get_last_interaction returns the newest event involving a contact or group of any type, call logs and media included
send_message to a person or a group, and send_media for an image, video, document or audio taken from a path, a URL or inline content — with a caption, or sent as a voice note
download_media pulls an attachment back out of a message
The linked session is stored as a browser profile and reused on later runs, so pairing is a one-time step

Requirements

Node.js 20 or newer, published as mcp-whatsapp-web and launched over stdio with npx. It drives a browser: the Chromium Puppeteer downloads covers everything except videos and GIFs, which need a real Chrome or Edge — both auto-detected, or named through BROWSER_EXECUTABLE_PATH. ffmpeg is bundled. The session lives in whatsapp-sessions and moves with WHATSAPP_SESSION_DIR, and setting WHATSAPP_PAIRING_PHONE_NUMBER logs a pairing code at startup instead of waiting for a QR scan. MCP_HTTP_PORT additionally exposes the server at http://127.0.0.1:<port>/mcp from the same process; that endpoint controls your personal account, so it binds to 127.0.0.1 by default and MCP_OAUTH puts a bearer token in front of it.

Setup effort

One command — npx -y mcp-whatsapp-web