WAHA

You can run a MCP server that lets AI assistants access and control WhatsApp through the WAHA platform. This server exposes MCP-compliant resources and tools for chats, messages, groups, contacts, and presence, enabling seamless integration with AI workflows.

How to use

To use this MCP server with an MCP client, connect your client to a local or remote MCP endpoint that implements the WAHA MCP server. You can manage chats, fetch messages, send messages, and access context-aware resources such as recent chats and chat histories. Use the available resources to provide context to your AI assistant and drive actions in WhatsApp through WAHA.

How to install

Prerequisites: Node.js and npm installed on your machine.

1. Clone the project repository.

2. Install dependencies.

npm install

3. Configure your WAHA API connection by creating your environment file and filling in details.

cp .env.example .env

4. Start in development mode for automatic reloads.

npm run dev

5. Build for production and start the server.

npm run build
npm start

Usage with Claude Desktop configuration (MCP client integration)

You can run the WAHA MCP server as a local process and connect it to Claude Desktop or other MCP clients. Use the provided command and absolute paths as shown in examples.

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"
      }
    }
  }
}

Available tools

Chat management

Get overview of recent WhatsApp chats and manage chat visibility and state.

waha_get_chats

Retrieve an overview of recent chats.

waha_get_messages

Fetch messages from a specific chat.

waha_mark_chat_read

Mark messages in a chat as read.

waha_mark_chat_unread

Mark a chat as unread.

waha_clear_chat_messages

Clear all messages from a chat (destructive operation).

waha_delete_chat

Delete a chat completely (destructive operation).

waha_archive_chat

Archive a chat.

waha_unarchive_chat

Unarchive a chat.

waha_get_chat_picture

Get the profile picture URL for a chat.

Messaging

Send, retrieve, and manage messages including media and location.

waha_send_message

Send a text message to a chat.

waha_send_media

Send images, videos, or documents.

waha_send_audio

Send audio or voice messages.

waha_send_location

Send location coordinates.

waha_send_contact

Send contact cards in vCard format.

waha_edit_message

Edit a sent message (only your own messages).

waha_delete_message

Delete a specific message (destructive).

waha_pin_message

Pin a message in a chat.

waha_unpin_message

Unpin a message in a chat.

waha_react_to_message

Add or remove an emoji reaction to a message.

waha_star_message

Star or unstar a message.

Groups

Manage groups, members, and group settings.

waha_get_groups

List all groups with filtering and pagination.

waha_get_groups_count

Get total number of groups.

waha_get_group_info

Get detailed info about a specific group.

waha_get_group_picture

Get group profile picture URL.

waha_set_group_picture

Set or update group profile picture.

waha_delete_group_picture

Remove group profile picture.

waha_create_group

Create a new WhatsApp group.

waha_update_group_subject

Change group name/subject.

waha_update_group_description

Update group description.

waha_leave_group

Leave a group.

waha_get_group_participants

List all members in a group.

waha_add_group_participants

Add members to a group (admin required).

waha_remove_group_participants

Remove members from a group (admin required).

waha_promote_group_admin

Promote participants to admin (admin required).

waha_demote_group_admin

Demote admin privileges (admin required).

waha_get_group_invite_code

Get group invite link.

waha_revoke_group_invite_code

Revoke invite link and generate a new one (admin required).

waha_join_group

Join a group using an invite code/link.

waha_get_group_join_info

Get group info from an invite link without joining.

waha_set_group_messages_admin_only

Toggle admin-only messaging (admin required).

waha_set_group_info_admin_only

Toggle admin-only group info editing (admin required).

Contacts

Access contact details and management.

waha_get_contact

Get contact information by ID.

waha_get_all_contacts

List all contacts with pagination.

waha_check_contact_exists

Check if a phone number is registered on WhatsApp.

waha_get_contact_about

Get a contact's about/status text.

waha_get_contact_profile_picture

Get a contact's profile picture URL.

waha_block_contact

Block a contact.

waha_unblock_contact

Unblock a contact.

Presence

Query and manage presence information.

waha_get_presence

Get presence status for a chat.

waha_subscribe_presence

Subscribe to presence updates for a chat.

waha_get_all_presence

Get all subscribed presence information.

waha_set_presence

Set your own presence status.