What can you do with this 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).

Which integrations are available for this server?

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.

How do I use WAHA MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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)

Installation

Clone this repository
Install dependencies:
```
npm install
```
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:

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

Install Server

A

security – no known vulnerabilities

F

license - not found

A

quality - confirmed to work

How are these scores calculated?

Resources

Need Help?

Report Issue

Related Servers

Tools

View all tools

WAHA MCP Server

WAHA MCP Server

Features

Installation

Configuration

Development

Build the project

Run in development mode with auto-reload

Test with MCP Inspector

Run in production

Usage with Claude Desktop

Available Tools

Chat Management

Messaging

Groups

Contacts

Presence

MCP Resources

Available Resources

Project Structure

Chat ID Format

License

Resources

Tools

Latest Blog Posts

MCP directory API