check_auth_status
Check if the WhatsApp client is authenticated and connected
LABSCO SUMMARY
A personal WhatsApp account an agent can read and write — with the terms-of-service question that comes attached.
This automates your personal account as a linked device rather than going through 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 links to your own WhatsApp account as a device — through WhatsApp Web in a browser by default, or through the optional Baileys backend with no browser. 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 saved — as a browser profile by default, in a SQLite file under Baileys — and reused on later runs, so pairing is a one-time step for each backend
Requirements
Node.js 22 or newer. Clients either run the published package with npx -y mcp-whatsapp-web, or launch dist/index.js with node from a clone of the repository built with npm install and npm run build; both speak stdio. The default whatsapp-web.js backend 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. Its session lives in whatsapp-sessions and moves with WHATSAPP_SESSION_DIR. Set WHATSAPP_BACKEND=baileys to run with no browser at all; that backend needs the optional dependencies, including the native better-sqlite3 module, is paired separately, and keeps its session in BAILEYS_SESSION_DIR. ffmpeg is bundled, 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:<YOUR_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
USE CASES
01
Linking the account the first time
Ask for the QR code and scan it from Linked Devices, or set a phone number and type the 8-character pairing code instead, then confirm the session is live.
02
Finding what someone told you
Search the contact, resolve their number to a chat, then read the messages from that chat rather than the chat summary.
03
Reading around a message you already found
get_message_by_id opens the one you have, and get_message_context returns the messages surrounding it in the same chat.
04
Sending a file to a chat or a group
send_media takes a local path, a URL or inline content, with a caption, and can send audio as a voice note instead of an attachment.
05
Pulling an attachment out of a thread
Find the message in the chat history, then download its media and hand the content back to the model.
06
Switching to a different WhatsApp account
logout clears the stored session, and the next QR code links the new phone.
17 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
download_media
Download media from a WhatsApp message and return its content.
get_chat_by_id
Get WhatsApp chat metadata by JID.
get_contact_by_id
Get contact details by JID.
get_direct_chat_by_contact_number
Get direct WhatsApp chat JID by contact phone number (less reliable, use get_chat_by_id if JID is known).
get_last_interaction
Get the most recent event involving a specific contact or group JID. IMPORTANT: this returns the newest event of ANY type - including call logs, media, and system notifications, which have an empty "body" - NOT necessarily the last text message. To read what was actually said, use list_messages instead.
get_message_by_id
Get a specific WhatsApp message by its ID.
get_message_context
Get recent messages around a specific message ID within its chat (context accuracy depends on fetch limit).
get_qr_code
Get the latest WhatsApp QR code as an image for authentication
list_chats
Get WhatsApp chats sorted by recent activity. Note: the "lastMessage" field is the newest event of ANY type (a call shows as type "call_log" with an empty body, media as "image"/"video", etc.) - NOT necessarily the last text message, and chat order reflects any activity, not just texts. To read actual conversation content, use list_messages.
list_messages
Get WhatsApp messages from a specific chat. This is the source of truth for actual message content: use it whenever the question is about what someone said/wrote. Entries include non-text events too (check the "type" field: "chat" = text message, "call_log" = call, "ptt" = voice note, "image"/"video" = media; non-text entries may have an empty "body").
logout
Logout from WhatsApp and clear the current session
ping
request_pairing_code
Request a pairing code as a text-based alternative to scanning the QR code. The user enters the returned 8-character code on their phone under Settings > Linked Devices > Link a device > "Link with phone number instead".
search_contacts
Search WhatsApp contacts by name or phone number.
send_media
Send media (image, video, document, audio) via WhatsApp.
send_message
Send a WhatsApp text message to a person or group.
BEFORE YOU INSTALL
What to know first
Tools you get
17 tools when we connected. The project's README still lists get_contact, get_chat, get_message, send_file and send_audio_message, which the server no longer has — use get_contact_by_id, get_chat_by_id, get_message_by_id and send_media instead.
Requires
- Node.js >= 22.0.0
- npm or yarn
- Google Chrome or Microsoft Edge (auto-detected; only needed for sending videos/GIFs — everything else works with the Chromium that puppeteer downloads automatically)
Where it runs
All 4 documented setups run the server on your machine.
CONTEXT COST
Light Standing cost
Rated by the size of the 17 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
Build from source
Clone this repository
TERMINAL
git clone https://github.com/mario-andreschak/mcp-whatsapp-web.git
cd mcp-whatsapp-webInstall dependencies
TERMINAL
npm installBuild the project
TERMINAL
npm run buildnpx
TERMINAL
npx -y mcp-whatsapp-webMCP Clients
Claude Desktop — local build, Cursor — local build
JSON
{
"mcpServers": {
"whatsapp": {
"command": "node",
"args": [
"<YOUR_PATH_TO_DIST>/index.js"
]
}
}
}<YOUR_PATH_TO_DIST> is the dist folder inside the mcp-whatsapp-web folder you cloned and built, written as an absolute path — dist/index.js only exists after npm run build.
Claude Desktop — npx, Cursor — npx
JSON
{
"mcpServers": {
"whatsapp": {
"command": "npx",
"args": [
"-y",
"mcp-whatsapp-web"
]
}
}
}Runs the published npm package mcp-whatsapp-web, which the author builds from this repository, so no clone or build is needed. Set WHATSAPP_SESSION_DIR in env to an absolute folder so the linked session is found again whichever directory the client starts in.
