WhatsApp HTTP API (WAHA) with Model Context Protocol integration for programmatic WhatsApp automation, messaging, contact management, chat operations, channel management, and authentication
This MCP server exposes 48 WhatsApp tools via STDIO transport. Naming conventions are mostly consistent (verb_noun pattern: get_, create_, delete_, list_, etc.). Descriptions exist for all tools and are moderately detailed (averaging ~120-180 characters), which is acceptable. However, parameter schemas are severely under-specified: most tools declare only basic string/number types with minimal constraint information. For example, 'auth-qr' accepts {"session": {"type": "string", "description": "Session identifier"}}, no format, length bounds, or pattern constraints. Output schemas are not documented anywhere in the visible code. Parameter descriptions are present but often terse (12-20 chars), below the production baseline of 72 chars. Error handling is not visible in the tool definitions, no recovery guidance, no categorization of errors. No tool declares permissions, audit logging, or security requirements. The large number of tools (48) masks inconsistencies: some like 'chats-get-messages' mention pagination guidance in their description, while others offer no such context. Destructive tools (delete, clear) lack confirmation/dry-run patterns. Overall, this server has the scaffolding of a multi-tool system but lacks the depth needed for production agent use.
Call HTTP API for certain method if no native MCP tools available. Before calling fetch "api-openapi" tool to get the latest openapi spec. Use it as last option if no native tools are found.
Get the latest OpenAPI schema for the HTTP API available to call in the "api-call" tool. Use it as a last option if no native tools are found. Find appropriate /api/send.* methods to send messages to direct chats (lid, c.us), groups (g.us) and channels/newsletter (@newsletter). Use api/:session/status to send status.
Purge an app's stored data (messages, caches) for a session. The app itself stays configured and keeps working.
Get the pending passkey (WebAuthn) challenge for a session in PASSKEY_REQUIRED status. Fails with 422 when nothing is pending. You cannot sign the challenge yourself - the assertion has to be produced by an authenticator on the https://web.whatsapp.com origin (the WAHA browser extension, or the DevTools fallback). Hand the challenge to the user, then submit the result with auth-passkey-submit.
Finish passkey pairing after the user confirmed the code matches the one shown on their phone. Only call it once the user has verified the code from auth-passkey-confirmation.
Parameter schemas lack type constraints, format declarations, and enumeration of valid values. All 48 tools declare only basic {'type': 'string'} or {'type': 'number'} with no bounds, patterns, or enum constraints. LLMs cannot infer valid options (e.g., for 'channels-search-by-view', no enum is visible; for 'chats-pin-message', no numeric bounds on 'duration'). This forces the agent to make blind guesses.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 57 | 2026-07-28+ | v2 |
Get the pending passkey confirmation code for a session in PASSKEY_CONFIRMATION_REQUIRED status. Fails with 422 when nothing is pending. Show the code to the user, ask them to check it matches the one on their phone, then call auth-passkey-confirm.
Submit the WebAuthn assertion produced by navigator.credentials.get() to finish passkey pairing. Get the challenge from auth-passkey-challenge first. After this the session usually goes straight to WORKING; if it goes to PASSKEY_CONFIRMATION_REQUIRED instead, follow up with auth-passkey-confirmation.
Get QR code to pair WhatsApp Session. The first QR code is valid for 60 seconds; each subsequent code is valid for 20 seconds. If the code expires before scanning, call this tool again to get a fresh one. If you run out of codes the server closes the connection — reconnect and start over.
Request a one-time pairing code for phone-number-based authentication (alternative to QR). Leave method empty for Web pairing.
Reject an incoming WhatsApp call
Create a new WhatsApp channel
Delete a WhatsApp channel
Follow a WhatsApp channel
Get channel information by ID (123@newsletter) or invite code/link
Get list of known WhatsApp channels for a session
Preview recent messages from a channel by ID (123@newsletter) or invite code/link
Mute notifications for a WhatsApp channel
Search for public WhatsApp channels by text query
Search for public WhatsApp channels by view, countries, and categories
Get available category options for channel search
Get available country codes for channel search
Get available view options for channel search (e.g. RECOMMENDED)
Unfollow a WhatsApp channel
Unmute notifications for a WhatsApp channel
Archive a chat
Delete all messages from a chat
Delete a chat
Delete a specific message from a chat
Edit the text of a sent message
Get a specific message by its ID
Get messages in a chat. To retrieve all messages, paginate by incrementing the offset by limit until the returned array is empty or shorter than the limit. To fetch media for a specific message, use chats-get-message with that message id and downloadMedia=true instead of fetching it here. Use downloadMediaMimetypes to download only media with the given mimetypes (prefix match).
Get the profile picture URL for a chat
Get list of chats for a session
Get chats overview with last message, name, and picture. Sorted by last message timestamp
Get chats overview via POST body — use this instead of chats-overview when filtering by many chat ids
Pin a message in a chat
Mark messages as read in a chat
Unarchive a chat
Unpin a message in a chat
Block a contact
Check whether a phone number is registered in WhatsApp
Get basic contact info. Always returns a result even if the number is not registered in WhatsApp — use contacts-check-exists to verify registration.
Get the contact's "about" / status text. Returns null if privacy settings block access.
Get all contacts for a session
Get the contact's profile picture URL. Returns null if privacy settings block access.
Unblock a contact
Create or update a contact in the phone address book. May not work if multiple WhatsApp apps are installed on the same phone.
Get a screenshot of the current WhatsApp Web page (WEBJS/WPP only)
Output schemas are not documented. No tool definition shows what fields are returned, their types, or how they chain to downstream tools. For example, 'chats-get-messages' should document that it returns an array of message objects with id, timestamp, sender, text, media_url, etc., but this is invisible. Agents cannot plan multi-step workflows without knowing what data they'll receive.
Destructive and sensitive tools lack confirmation or dry-run patterns. Tools like 'chats-delete', 'chats-clear-messages', 'chats-delete-message', 'channels-delete', and 'apps-purge' (marked DESTRUCTIVE) have no warning mechanism or rollback path. An agent can irreversibly delete all messages in a chat with no guard rail.
Error handling and recovery guidance are absent from tool definitions. No tool description mentions what errors it might return, how to interpret them, or what to do next. For example, 'auth-passkey-challenge' states 'Fails with 422 when nothing is pending' in the description, which is good, but most tools offer no such guidance. Agents cannot self-correct on failures.
Parameter descriptions are often under 20 characters and lack context. Examples: 'calls-reject' has session param 'Session identifier' (20 chars); 'chats-list' has session param 'Session identifier' (20 chars). These are at the lower bound and provide minimal guidance. Production baseline is 72 chars. Most parameters lack format hints, allowed values, or constraints on input.
No tool declares permissions, scopes, or authorization requirements. A production-grade system would require each tool to declare what permissions it needs (e.g., 'read:messages', 'write:contacts', 'admin:delete'). This prevents least-privilege agent configuration and audit visibility.
Pagination support is mentioned in some descriptions (e.g., 'chats-get-messages' advises 'paginate by incrementing the offset by limit') but is not enforced in parameter schemas. No tools expose 'limit', 'offset', or 'page' parameters in their visible input. Large result sets could exhaust context windows.
Some tools accept overly generic parameters that could benefit from splitting. For example, 'api-call' takes a generic 'body' parameter of type 'object'. Without strict validation of that object's shape, agents risk malformed payloads. A well-designed fallback tool should guide agents toward native tools first, not serve as a catch-all without validation.