WAHA

WAHA MCP Server bridges the WhatsApp HTTP API with Claude Desktop and MCP-compatible clients, enabling seamless WhatsApp automation and AI-powered workflows. You can manage messaging, chats, media, groups, and interactive tasks through MCP while benefiting from secure API handling and fast, TypeScript-powered operation.

How to use

You will run the WAHA MCP Server as a local or remote process and connect it to your MCP client, such as Claude Desktop, via the MCP protocol. Start by configuring your client to load the WAHA MCP server, supply your WAHA API key, and point it to your WAHA instance. Once connected, you can send and receive messages, manage chats and groups, and trigger automated workflows using the wide set of tools exposed by the server. Use Interactive Workflows to ask users for input via WhatsApp when needed, allowing Claude Code to proceed without pausing for manual console input.

How to install

Prerequisites you need before installing: Node.js 18 or newer, a running WAHA instance, and a WAHA API key.

1. Clone the repository and install dependencies.

git clone https://github.com/dudu1111685/waha-mcp.git
cd waha-mcp
npm install
npm run build

Additional setup to run

2. Set environment variables for WAHA access. Create a .env file or export variables in your shell.

export WAHA_API_KEY="your-api-key-here"
export WAHA_URL="http://localhost:3001"  # optional, defaults to localhost:3001

Available tools

waha_list_sessions

List all sessions and their statuses

waha_get_session

Get detailed information about a specific session

waha_create_session

Create a new session

waha_start_session

Start a stopped session

waha_stop_session

Stop a running session

waha_restart_session

Restart a session

waha_delete_session

Delete a session permanently

waha_logout_session

Disconnect a WhatsApp account from a session

waha_get_qr_code

Retrieve the QR code for WhatsApp authentication

waha_request_pairing_code

Request a code to pair a phone number

waha_check_auth_status

Check the authentication status of a session

waha_send_text

Send a text message

waha_send_image

Send an image from a local file or URL

waha_send_video

Send a video with automatic conversion to WhatsApp format

waha_send_voice

Send a voice message with automatic conversion to WhatsApp format

waha_send_file

Send any document or file

waha_send_location

Send a location pin

waha_send_contact

Send a contact vCard

waha_send_poll

Create and send a poll

waha_react_to_message

React to a message with emoji

waha_forward_message

Forward a message

waha_get_messages

Retrieve messages with pagination

waha_delete_message

Delete a message

waha_edit_message

Edit a sent message

waha_mark_as_read

Mark messages as read

waha_star_message

Star or unstar a message

waha_list_chats

List all chats

waha_get_chat

Get detailed chat information

waha_archive_chat

Archive or unarchive a chat

waha_pin_chat

Pin or unpin a chat

waha_mute_chat

Mute or unmute a chat

waha_delete_chat

Delete a chat

waha_clear_chat

Clear all messages in a chat

waha_get_contacts

Get all contacts

waha_get_contact

Get information about a contact

waha_check_number_exists

Check if a number exists on WhatsApp

waha_block_contact

Block or unblock a contact

waha_get_profile_picture

Get a contact's profile picture URL

waha_create_group

Create a new group

waha_list_groups

List all groups

waha_get_group

Get detailed group information

waha_get_group_participants

List group participants

waha_add_group_participants

Add participants to a group

waha_remove_group_participants

Remove participants from a group

waha_promote_group_participant

Promote a participant to admin

waha_demote_group_participant

Demote an admin to a regular member

waha_update_group_subject

Update the group subject

waha_update_group_description

Update the group description

waha_update_group_picture

Update the group profile picture

waha_leave_group

Leave a group

waha_get_group_invite_code

Get a group invite link

waha_revoke_group_invite

Revoke and regenerate a group invite link

waha_set_presence

Set presence to online or offline

waha_get_presence

Get a contact's presence

waha_start_typing

Show a typing indicator

waha_stop_typing

Stop typing indicator

waha_send_status

Post a text status or story

waha_get_labels

Get all labels

waha_create_label

Create a label

waha_delete_label

Delete a label

waha_add_label_to_chat

Add a label to a chat

waha_remove_label_from_chat

Remove a label from a chat

ask_user_via_whatsapp

New interactive tool to send a question via WhatsApp and wait for user reply