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

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., [email protected])
• Group chats: <group_id>@g.us (e.g., [email protected])

You can get chat IDs by using the waha_get_chats tool first.

License

ISC