WAHA MCP Server
The WAHA MCP Server enables AI assistants to interact with WhatsApp through the WAHA (WhatsApp HTTP API) platform, providing comprehensive WhatsApp management capabilities.
Chat Management: Retrieve recent chats with previews and unread counts, get message history, mark chats as read/unread, archive/unarchive, clear/delete chats, and get chat profile pictures.
Messaging: Send text (with link previews/reply support), media (images, videos, documents via URL or base64), audio/voice, location, and contact cards (vCard). Also supports editing, deleting, pinning/unpinning, reacting to, and starring/unstarring messages.
Group Management: List, create, and get detailed group info; set/delete group pictures; update group name/description; leave groups; manage participants (add, remove, promote/demote admins); get, revoke, or join via invite links; preview group info from an invite link; and toggle admin-only messaging/info editing restrictions.
Contact Management: Look up contacts, list all contacts with sorting/pagination, check if a phone number is registered on WhatsApp, get contact about/status text and profile pictures, and block/unblock contacts.
Presence: Get, subscribe to, and retrieve presence updates (online/offline/typing) for chats, and set your own presence status (online, offline, typing, recording, paused).
MCP Resources: Access cached, context-aware WhatsApp data — recent chats overview (waha://chats/overview) and chat message history (waha://chat/{chatId}/messages).
Enables AI assistants to interact with WhatsApp through the WAHA (WhatsApp HTTP API) platform, providing tools for chat management, sending and retrieving messages, and marking messages as read.
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., "@WAHA MCP Server send a message to John at 1234567890 saying I'll be 10 minutes late"
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.
WAHA MCP Server
A Model Context Protocol (MCP) server that enables AI assistants to interact with WhatsApp through the WAHA (WhatsApp HTTP API) platform.
Features
Chat Management: Get overview of recent WhatsApp chats
Message Operations: Retrieve, send, and mark messages as read
MCP Resources: Access WhatsApp data as context-aware resources with caching
MCP Integration: Full compatibility with MCP clients (stdio transport)
Related MCP server: WhatsApp Cloud API MCP Server
Installation
Clone this repository
Install dependencies:
npm installConfigure your WAHA API connection:
cp .env.example .envThen edit
.envwith your WAHA instance details.
Configuration
Required environment variables in .env:
WAHA_BASE_URL: Your WAHA server URL (e.g.,http://localhost:3000)WAHA_API_KEY: Your WAHA API key for authenticationWAHA_SESSION: WhatsApp session name (default:default)
Development
Build the project
npm run buildRun in development mode with auto-reload
npm run devTest with MCP Inspector
The MCP Inspector is a web-based tool to test your MCP server interactively:
npm run inspectorThis will:
Start the WAHA MCP server
Launch the MCP Inspector web UI
Open your browser automatically
Use the inspector to:
Test all tools interactively
View tool schemas
See request/response data
Debug tool calls
Run in production
npm startUsage with Claude Desktop
Add this to your Claude Desktop MCP configuration:
Windows:
{
"mcpServers": {
"waha": {
"command": "node",
"args": ["C:\\Users\\YourUsername\\path\\to\\waha\\dist\\index.js"],
"env": {
"WAHA_BASE_URL": "http://localhost:3000",
"WAHA_API_KEY": "your-api-key-here",
"WAHA_SESSION": "default"
}
}
}
}Mac/Linux:
{
"mcpServers": {
"waha": {
"command": "node",
"args": ["/absolute/path/to/waha-mcp-server/dist/index.js"],
"env": {
"WAHA_BASE_URL": "http://localhost:3000",
"WAHA_API_KEY": "your-api-key-here",
"WAHA_SESSION": "default"
}
}
}
}Note: Windows users should use double backslashes (
\\) in paths.
Available Tools
Chat Management
Tool | Description |
| Get overview of recent WhatsApp chats |
| Get messages from a specific chat |
| Mark messages in a chat as read |
| Mark a chat as unread |
| Clear all messages from a chat (destructive) |
| Delete a chat completely (destructive) |
| Archive a chat |
| Unarchive a chat |
| Get the profile picture URL for a chat |
Messaging
Tool | Description |
| Send a text message to a chat |
| Send images, videos, or documents |
| Send audio/voice messages |
| Send location coordinates |
| Send contact card(s) using vCard format |
| Edit a sent message (own messages only) |
| Delete a specific message (destructive) |
| Pin a message in a chat |
| Unpin a message in a chat |
| Add or remove an emoji reaction |
| Star or unstar a message |
Groups
Tool | Description |
| List all groups with filtering and pagination |
| Get total number of groups |
| Get detailed info about a specific group |
| Get group profile picture URL |
| Set or update group profile picture |
| Remove group profile picture |
| Create a new WhatsApp group |
| Change group name/subject |
| Update group description |
| Leave a group |
| List all members in a group |
| Add member(s) to a group (admin required) |
| Remove member(s) from a group (admin required) |
| Promote participant(s) to admin (admin required) |
| Remove admin privileges (admin required) |
| Get group invite link |
| Revoke invite link and generate a new one (admin required) |
| Join a group using an invite code/link |
| Get group info from invite link without joining |
| Toggle admin-only messaging (admin required) |
| Toggle admin-only group info editing (admin required) |
Contacts
Tool | Description |
| Get contact information by ID |
| List all contacts with pagination |
| Check if a phone number is registered on WhatsApp |
| Get contact's about/status text |
| Get contact's profile picture URL |
| Block a contact |
| Unblock a contact |
Presence
Tool | Description |
| Get online/offline/typing status for a chat |
| Subscribe to presence updates for a chat |
| Get all subscribed presence information |
| Set your own presence status (online, offline, typing, etc.) |
MCP Resources
In addition to tools, the server exposes MCP Resources for context-aware data access:
Available Resources
waha://chats/overview- Recent chats with last message previewswaha://chat/{chatId}/messages- Message history from a specific chat
Resources support query parameters for filtering and pagination. Data is cached for 5 minutes for performance.
Project Structure
waha-mcp-server/
├── src/
│ ├── index.ts # Server entry point
│ ├── config.ts # Configuration management
│ ├── types/ # TypeScript type definitions
│ ├── tools/ # MCP tool implementations
│ ├── resources/ # MCP resource implementations
│ │ ├── base/ # Base resource class
│ │ ├── implementations/ # Concrete resources
│ │ ├── cache/ # LRU caching layer
│ │ └── manager/ # Resource registry
│ └── client/ # WAHA API client
├── dist/ # Built JavaScript output
├── .env # Your configuration (not in git)
├── .env.example # Configuration template
├── package.json
└── tsconfig.jsonChat ID Format
WhatsApp chat IDs have specific formats:
Individual chats:
<phone_number>@c.us(e.g.,1234567890@c.us)Group chats:
<group_id>@g.us(e.g.,123456789012345678@g.us)
You can get chat IDs by using the waha_get_chats tool first.
License
ISC
Available Tools
52 toolswaha_add_group_participantsB
Add member(s) to a group. Requires admin privileges.
Inputs: groupId (required), participants (required).
waha_archive_chatC
Archive a chat. Archived chats are hidden from the main chat list.
Inputs: chatId (required).
waha_block_contactC
Block a contact.
Inputs: contactId (required).
waha_check_contact_existsC
Check if phone number is registered on WhatsApp.
Inputs: phone (required).
waha_clear_chat_messagesA
Clear all messages from a chat. WARNING: This is a destructive operation that cannot be undone.
Inputs: chatId (required).
waha_create_groupC
Create a new WhatsApp group.
Inputs: name (required), participants (required).
waha_delete_chatA
Delete a chat completely. WARNING: This is a destructive operation that cannot be undone.
Inputs: chatId (required).
waha_delete_group_pictureC
Remove group profile picture.
Inputs: groupId (required).
waha_delete_messageA
Delete a specific message from a chat. This is a destructive operation and cannot be undone.
Inputs: chatId (required), messageId (required).
waha_demote_group_adminB
Remove admin privileges from participant(s). Requires admin privileges.
Inputs: groupId (required), participants (required).
waha_edit_messageA
Edit a sent message in a chat. Only works for messages sent by the bot.
Inputs: chatId (required), messageId (required), text (required), linkPreview, +1 more.
waha_get_all_contactsC
List all contacts with pagination.
Inputs: sortBy, sortOrder, limit, offset.
waha_get_all_presenceB
Get all subscribed presence information.
Inputs: no named parameters.
waha_get_chat_pictureA
Get the profile picture URL for a chat. Uses 24-hour cache by default.
Inputs: chatId (required), refresh.
waha_get_chatsA
Get overview of recent WhatsApp chats. Returns chat ID, name, last message preview, and unread count. Default limit is 10 chats.
Inputs: limit, offset, chatIds.
waha_get_contactB
Get contact information by ID.
Inputs: contactId (required).
waha_get_contact_aboutC
Get contact's about/status text.
Inputs: contactId (required).
waha_get_contact_profile_pictureC
Get contact's profile picture URL.
Inputs: contactId (required), refresh.
waha_get_group_infoC
Get detailed information about a specific group.
Inputs: groupId (required).
waha_get_group_invite_codeC
Get group invite link.
Inputs: groupId (required).
waha_get_group_join_infoA
Get group information from invite link without joining.
Inputs: code (required).
waha_get_group_participantsC
List all members in a group.
Inputs: groupId (required).
waha_get_group_pictureB
Get group profile picture URL.
Inputs: groupId (required), refresh.
waha_get_groupsC
List all groups with filtering and pagination options.
Inputs: sortBy, sortOrder, limit, offset, +1 more.
waha_get_groups_countB
Get total number of groups.
Inputs: no named parameters.
waha_get_messagesA
Get messages from a specific WhatsApp chat. Returns message content, sender, timestamp, and status. Default limit is 10 messages.
Inputs: chatId (required), limit, offset, downloadMedia.
waha_get_presenceA
Get online/offline/typing status for a chat. Auto-subscribes if not already subscribed.
Inputs: chatId (required).
waha_join_groupC
Join a group using invite code/link.
Inputs: code (required).
waha_leave_groupC
Leave a group.
Inputs: groupId (required).
waha_mark_chat_readB
Mark messages in a chat as read. Can specify number of recent messages or time range in days.
Inputs: chatId (required), messages, days.
waha_mark_chat_unreadC
Mark a chat as unread. This adds an unread indicator to the chat.
Inputs: chatId (required).
waha_pin_messageC
Pin a message in a chat. Pinned messages appear at the top of the chat.
Inputs: chatId (required), messageId (required), duration.
waha_promote_group_adminB
Promote participant(s) to group admin. Requires admin privileges.
Inputs: groupId (required), participants (required).
waha_react_to_messageA
Add an emoji reaction to a message. To remove a reaction, send an empty string.
Inputs: messageId (required), reaction (required).
waha_remove_group_participantsB
Remove member(s) from a group. Requires admin privileges.
Inputs: groupId (required), participants (required).
waha_revoke_group_invite_codeA
Revoke current invite link and generate a new one. Requires admin privileges.
Inputs: groupId (required).
waha_send_audioC
Send audio/voice messages to a WhatsApp chat. Supports URL or base64 data.
Inputs: chatId (required), mimetype (required), fileUrl, fileData, +2 more.
waha_send_contactB
Send contact card(s) to a WhatsApp chat using vCard format.
Inputs: chatId (required), vcard (required), replyTo.
waha_send_locationC
Send location coordinates to a WhatsApp chat.
Inputs: chatId (required), latitude (required), longitude (required), title, +1 more.
waha_send_mediaC
Send media files (images, videos, or documents) to a WhatsApp chat. Supports URL or base64 data.
Inputs: chatId (required), mediaType (required), mimetype (required), fileUrl, +4 more.
waha_send_messageC
Send a text message to a WhatsApp chat. Returns message ID and delivery timestamp.
Inputs: chatId (required), text (required), replyTo, linkPreview.
waha_set_group_info_admin_onlyA
Toggle whether only admins can edit group info. Requires admin privileges.
Inputs: groupId (required), adminsOnly (required).
waha_set_group_messages_admin_onlyA
Toggle whether only admins can send messages. Requires admin privileges.
Inputs: groupId (required), adminsOnly (required).
waha_set_group_pictureC
Set or update group profile picture.
Inputs: groupId (required), fileUrl, fileData.
waha_set_presenceC
Set your own presence status (online, offline, typing, recording, or paused).
Inputs: chatId (required), presence (required).
waha_star_messageC
Star or unstar a message.
Inputs: chatId (required), messageId (required), star (required).
waha_subscribe_presenceC
Subscribe to presence updates for a chat.
Inputs: chatId (required).
waha_unarchive_chatB
Unarchive a chat. Moves the chat back to the main chat list.
Inputs: chatId (required).
waha_unblock_contactB
Unblock a contact.
Inputs: contactId (required).
waha_unpin_messageC
Unpin a message in a chat.
Inputs: chatId (required), messageId (required).
waha_update_group_descriptionC
Update group description.
Inputs: groupId (required), description (required).
waha_update_group_subjectC
Change group name/subject.
Inputs: groupId (required), subject (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 52 tools
Most tools have distinct purposes with clear boundaries, such as waha_send_message for text versus waha_send_media for files. However, some overlap exists, like waha_get_chat_picture and waha_get_contact_profile_picture, which could cause minor confusion in selection, but descriptions help clarify the target (chat vs. contact).
All tool names follow a consistent waha_verb_noun pattern, using snake_case throughout. This predictability makes it easy for agents to understand and navigate the toolset without naming conflicts or style variations.
With 52 tools, the count is excessive for a WhatsApp automation server, leading to potential overwhelm and redundancy. A more focused set of 15-25 tools would better cover the domain without unnecessary complexity, as many operations could be consolidated (e.g., multiple group admin tools).
The toolset provides comprehensive coverage for WhatsApp interactions, including CRUD operations for chats, groups, contacts, and messages, along with advanced features like presence management and media handling. No obvious gaps are present, ensuring agents can handle full workflows without dead ends.
Maintenance
Related MCP Connectors
Read, search and reply to your WhatsApp chats from your AI, using your own number.
Send WhatsApp messages and templates, manage chats, contacts, broadcasts and AI agents.
Read, summarize and send your own WhatsApp messages from AI assistants (OAuth 2.1).
Operate WhatsApp from an agent: read conversations and contacts, send messages, by API key.
Related MCP Servers
- 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.10130 npm3MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to send WhatsApp messages, templates, and retrieve media through the WhatsApp Cloud API. Provides webhook handling and seamless integration with Meta's WhatsApp Business platform.23ISC
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to manage WhatsApp: list chats, send and receive messages, download media, and transcribe voice notes via the unofficial Baileys library.93 npmMIT
- AlicenseBqualityCmaintenanceEnables an AI assistant to read and send WhatsApp messages, search contacts and chats, manage messages and media, and sync history through the api-supp WhatsApp bridge's REST API.13MIT