Skip to main content
Glama

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

  1. Clone this repository

  2. Install dependencies:

    npm install
  3. Configure your WAHA API connection:

    cp .env.example .env

    Then edit .env with 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 authentication

  • WAHA_SESSION: WhatsApp session name (default: default)

Development

Build the project

npm run build

Run in development mode with auto-reload

npm run dev

Test with MCP Inspector

The MCP Inspector is a web-based tool to test your MCP server interactively:

npm run inspector

This will:

  1. Start the WAHA MCP server

  2. Launch the MCP Inspector web UI

  3. 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 start

Usage 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

waha_get_chats

Get overview of recent WhatsApp chats

waha_get_messages

Get 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)

waha_delete_chat

Delete a chat completely (destructive)

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

Tool

Description

waha_send_message

Send a text message to a chat

waha_send_media

Send images, videos, or documents

waha_send_audio

Send audio/voice messages

waha_send_location

Send location coordinates

waha_send_contact

Send contact card(s) using vCard format

waha_edit_message

Edit a sent message (own messages only)

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

waha_star_message

Star or unstar a message

Groups

Tool

Description

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 member(s) to a group (admin required)

waha_remove_group_participants

Remove member(s) from a group (admin required)

waha_promote_group_admin

Promote participant(s) to admin (admin required)

waha_demote_group_admin

Remove 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 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

Tool

Description

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 contact's about/status text

waha_get_contact_profile_picture

Get contact's profile picture URL

waha_block_contact

Block a contact

waha_unblock_contact

Unblock a contact

Presence

Tool

Description

waha_get_presence

Get online/offline/typing 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 (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 previews

  • waha://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.json

Chat 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 tools
waha_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

    B3.3/5.0

    Scored across 52 tools

    Disambiguation4/5

    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).

    Naming Consistency5/5

    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.

    Tool Count2/5

    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).

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      101
      30 npm
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to manage WhatsApp: list chats, send and receive messages, download media, and transcribe voice notes via the unofficial Baileys library.
      93 npm
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables 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.
      13
      MIT