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

• 🚀 Multi-Session Support: Manage multiple WhatsApp accounts simultaneously from one MCP server
• 🔐 Session Management: Complete control over WhatsApp sessions - create, start, stop, restart, authenticate
• 📝 Message Operations: Send, receive, edit, delete, pin, react, and mark messages as read
• 📁 Chat Management: Archive, delete, and organize chats with profile pictures
• 📊 Polls: Create and vote on polls with single or multiple answer options
• 📸 Status/Stories: Send and manage WhatsApp statuses (text, images, videos)
• 👥 Group Management: Full group control - create, manage members, settings, and invite links
• 👤 Contact Management: Check contacts, get info, profile pictures, block/unblock
• 🏷️ Labels: WhatsApp Business labels for chats and messages
• 📨 Rich Media: Send images, videos, audio, documents, locations, and contacts
• 👁️ Presence: Monitor and set online/typing status
• 🔄 Real-time Events: Webhook and WebSocket support for live updates
• 🎯 MCP Integration: Full compatibility with MCP clients like Claude Desktop
• ⏱️ Utility Tools: Sleep/wait functions for automation workflows and rate limiting

Total: 76+ comprehensive tools covering all major WhatsApp functionality and automation utilities!

✨ New: Multi-session support enables managing multiple WhatsApp accounts (personal, business, bots) from a single MCP server. Each tool accepts an optional session parameter to specify which account to use.

Installation

Option 1: Install from npm (Recommended)

The easiest way to use WAHA MCP Server:

npm install -g waha-mcp-server

Then configure your MCP client (see Configuration section below).

Option 2: Local Development Installation

For development or customization:

1. Clone the repository:

   git clone https://github.com/TheOneironaut/waha-mcp.git
   cd waha-mcp

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

4. Configure your WAHA API connection:

   cp .env.example .env

   Then edit .env with your WAHA instance details:

   WAHA_BASE_URL=https://your-waha-server.com
   WAHA_API_KEY=your-api-key-here
   # WAHA_SESSION=default  # Optional

5. Configure with Cursor (or Claude Desktop):

   Edit your MCP configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Cursor: Settings → Features → Claude → Edit Config

   For local installation, replace the path with where you cloned the repository:

   Example for Windows:

   {
     "mcpServers": {
       "waha": {
         "command": "node",
         "args": ["C:\\Users\\YourUsername\\waha-mcp\\dist\\index.js"],
         "env": {
           "WAHA_BASE_URL": "https://waha.goblindeals.org",
           "WAHA_API_KEY": "your-api-key-here"
         }
       }
     }
   }

   Example for macOS/Linux:

   {
     "mcpServers": {
       "waha": {
         "command": "node",
         "args": ["/Users/yourname/waha-mcp/dist/index.js"],
         "env": {
           "WAHA_BASE_URL": "https://waha.goblindeals.org",
           "WAHA_API_KEY": "your-api-key-here"
         }
       }
     }
   }

Configuration

For npm Installation

If you installed via npm (npm install -g waha-mcp-server), configure your MCP client:

Claude Desktop / Cursor

Edit your MCP configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Cursor: Settings → Features → Claude → Edit Config

Using npx (recommended - always uses latest version):

{
  "mcpServers": {
    "waha": {
      "command": "npx",
      "args": ["-y", "waha-mcp-server"],
      "env": {
        "WAHA_BASE_URL": "https://waha.goblindeals.org",
        "WAHA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Using installed binary:

{
  "mcpServers": {
    "waha": {
      "command": "waha-mcp-server",
      "env": {
        "WAHA_BASE_URL": "https://waha.goblindeals.org",
        "WAHA_API_KEY": "your-api-key-here"
      }
    }
  }
}

6. Restart Cursor/Claude Desktop to load the new MCP server.

Finding the Absolute Path

Windows (PowerShell):

cd path\to\waha-mcp
Get-Location
# Copy the output, e.g., C:\Users\YourName\waha-mcp

macOS/Linux:

cd path/to/waha-mcp
pwd
# Copy the output, e.g., /Users/yourname/waha-mcp

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: (Optional) Default WhatsApp session name to use when not specified in tool calls (default: default)

Multi-Session Support

The WAHA MCP Server now supports managing multiple WhatsApp sessions! Each tool accepts an optional session parameter:

• If provided: The tool operates on the specified session
• If not provided: Uses the WAHA_SESSION environment variable as default

Examples:

// Use default session from WAHA_SESSION env var
{
  "name": "waha_get_chats",
  "arguments": { "limit": 10 }
}

// Specify a different session
{
  "name": "waha_get_chats", 
  "arguments": { "session": "business", "limit": 10 }
}

// Work with multiple sessions at once
// List all sessions
{
  "name": "waha_list_sessions",
  "arguments": { "all": true }
}

// Update profile pictures for all sessions
// Get sessions, then for each session:
{
  "name": "waha_set_my_profile_picture",
  "arguments": {
    "session": "personal",
    "file": { "mimetype": "image/jpeg", "data": "base64..." }
  }
}

This enables powerful use cases like:

• Managing personal and business accounts separately
• Bulk operations across multiple accounts
• Different configurations per session

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 4 tools interactively
• View tool schemas
• See request/response data
• Debug tool calls

Run in production

npm start

Usage with Cursor and Claude Desktop

After installation, configure your MCP client to use the server.

Configuration File Locations

• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
• Cursor: Open Settings → Features → Claude → Edit Config

Basic Configuration (No Default Session)

Use this if you want to specify the session for each request:

{
  "mcpServers": {
    "waha": {
      "command": "node",
      "args": ["C:\\Users\\amitayb\\waha-mcp\\dist\\index.js"],
      "env": {
        "WAHA_BASE_URL": "https://waha.goblindeals.org",
        "WAHA_API_KEY": "0572a1f46333a4f11bbd6563ad1fc74c9dd90b698683d02036a76c7a3f74648c"
      }
    }
  }
}

Advanced Configuration (With Default Session)

Use this if you have a primary session you use most often:

{
  "mcpServers": {
    "waha": {
      "command": "node",
      "args": ["C:\\Users\\amitayb\\waha-mcp\\dist\\index.js"],
      "env": {
        "WAHA_BASE_URL": "https://waha.goblindeals.org",
        "WAHA_API_KEY": "0572a1f46333a4f11bbd6563ad1fc74c9dd90b698683d02036a76c7a3f74648c",
        "WAHA_SESSION": "bot10"
      }
    }
  }
}

Configuration Notes

Path Format:

• Windows: Use double backslashes \\ or forward slashes /
  • ✅ C:\\Users\\amitayb\\waha-mcp\\dist\\index.js
  • ✅ C:/Users/amitayb/waha-mcp/dist/index.js
• macOS/Linux: Use forward slashes /
  • ✅ /Users/yourname/waha-mcp/dist/index.js

WAHA_SESSION (Optional):

• ✅ If not provided: Specify session in each tool call
• ✅ If provided: Used as default when session not specified in tool call
• 💡 Tip: Set to your most-used session (e.g., "bot10", "default")

After Configuration

1. Save the configuration file
2. Restart Cursor or Claude Desktop
3. Verify: The WAHA tools should appear in the MCP tools list

Troubleshooting

Error: "npm error 404 Not Found - waha-mcp-server"

Problem: You tried to use npx waha-mcp-server but the package is not on npm.

Solution: This project is only available on GitHub. You must use local installation (see Installation section above). Update your configuration to use node with the path to dist/index.js:

{
  "command": "node",
  "args": ["C:\\full\\path\\to\\waha-mcp\\dist\\index.js"]
}

Error: "No server info found"

Problem: The MCP server failed to start.

Solutions:

1. Check the path: Make sure the path to dist/index.js is correct and absolute
2. Build the project: Run npm run build in the project directory
3. Check Node.js: Make sure Node.js is installed (node --version)
4. Check logs: Look at Cursor/Claude logs for detailed error messages

Error: "WAHA_BASE_URL environment variable is required"

Problem: Missing required configuration.

Solution: Add WAHA_BASE_URL and WAHA_API_KEY to the env section in your config:

{
  "env": {
    "WAHA_BASE_URL": "https://your-waha-server.com",
    "WAHA_API_KEY": "your-api-key-here"
  }
}

Server works in terminal but not in Cursor

Problem: Works with npm start but not in Cursor.

Solutions:

1. Use full paths: Don't use ~ or relative paths, use absolute paths
2. Check current directory: The MCP server runs from its own directory, not Cursor's
3. Verify environment variables: All config must be in the JSON config file

How to verify it's working

Run the test script:

cd /path/to/waha-mcp
node demo_multi_session.js

If this works, your installation is correct. The issue is likely with the Cursor/Claude configuration.

Multi-Session Usage Examples

Once configured, you can:

Use the default session (if WAHA_SESSION is set):

// Uses WAHA_SESSION from config
{
  "name": "waha_get_chats",
  "arguments": { "limit": 10 }
}

Use a specific session:

// Override to use a different session
{
  "name": "waha_get_chats",
  "arguments": {
    "session": "business",
    "limit": 10
  }
}

Work with multiple sessions:

// List all sessions on your WAHA server
{
  "name": "waha_list_sessions",
  "arguments": { "all": true }
}

// Send message from specific bot
{
  "name": "waha_send_message",
  "arguments": {
    "session": "bot10",
    "chatId": "[email protected]",
    "text": "Hello from bot10!"
  }
}

Available Tools

The WAHA MCP Server now provides 74+ comprehensive tools covering all major WAHA API capabilities:

📝 Message Management (4 tools)

• waha_get_chats: Get overview of recent chats with unread counts
• waha_get_messages: Retrieve messages from a specific chat
• waha_send_message: Send text messages with link preview and reply support
• waha_mark_chat_read: Mark messages as read in a chat

✏️ Message Operations (7 tools)

• waha_delete_message: Delete a specific message
• waha_edit_message: Edit a sent message
• waha_pin_message: Pin a message in a chat
• waha_unpin_message: Unpin a message
• waha_clear_chat_messages: Clear all messages from a chat
• waha_delete_chat: Delete a chat completely
• waha_star_message: Star or unstar a message

📁 Chat Management (6 tools)

• waha_archive_chat: Archive a chat
• waha_unarchive_chat: Unarchive a chat
• waha_mark_chat_unread: Mark a chat as unread
• waha_get_chat_picture: Get chat profile picture
• waha_react_to_message: React to a message with emoji

📨 Rich Media (6 tools)

• 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 cards (vCard)

📊 Polls (2 tools)

• waha_send_poll: Send polls with single or multiple answer options
• waha_send_poll_vote: Vote on existing polls

📸 Status/Stories (4 tools)

• waha_send_text_status: Send text status with custom styling
• waha_send_media_status: Send image/video status
• waha_get_statuses: Get available statuses from contacts
• waha_delete_status: Delete your own status

👥 Group Management (18 tools)

• waha_get_groups: List all groups with pagination
• waha_get_group_info: Get detailed group information
• waha_create_group: Create a new group
• waha_get_group_picture: Get group profile picture
• waha_set_group_picture: Set group profile picture
• waha_delete_group_picture: Remove group picture
• waha_update_group_subject: Update group name
• waha_update_group_description: Update group description
• waha_leave_group: Leave a group
• waha_get_group_participants: List group members
• waha_add_group_participants: Add members to group
• waha_remove_group_participants: Remove members from group
• waha_promote_group_admin: Promote members to admin
• waha_demote_group_admin: Demote admins
• waha_get_group_invite_code: Get group invite link
• waha_revoke_group_invite_code: Revoke and generate new invite link
• waha_join_group: Join group via invite code
• waha_get_group_join_info: Get group info from invite code
• waha_set_group_messages_admin_only: Restrict messaging to admins
• waha_set_group_info_admin_only: Restrict info changes to admins
• waha_get_groups_count: Get total group count

👤 Contact Management (7 tools)

• waha_get_contact: Get contact information
• waha_get_all_contacts: List all contacts with pagination
• waha_check_contact_exists: Check if phone number is on WhatsApp
• waha_get_contact_about: Get contact's status/about text
• waha_get_contact_profile_picture: Get contact's profile picture
• waha_block_contact: Block a contact
• waha_unblock_contact: Unblock a contact

🏷️ Labels (WhatsApp Business) (7 tools)

• waha_get_labels: Get all available labels
• waha_get_chat_labels: Get labels assigned to a chat
• waha_put_chat_labels: Assign labels to a chat
• waha_delete_chat_label: Remove label from a chat
• waha_get_message_labels: Get labels on a message
• waha_put_message_labels: Assign labels to a message
• waha_delete_message_label: Remove label from a message

👤 Profile Management (4 tools)

• waha_set_my_profile_name: Set your WhatsApp display name
• waha_set_my_profile_status: Set your About text
• waha_set_my_profile_picture: Upload/update profile picture
• waha_delete_my_profile_picture: Remove profile picture

👁️ Presence/Status (4 tools)

• waha_get_presence: Get presence info for a chat
• waha_subscribe_presence: Subscribe to presence updates
• waha_set_presence: Set your presence (online, typing, etc.)
• waha_get_all_presence: Get all subscribed presence info

🔐 Session Management (13 tools)

• waha_list_sessions: List all WhatsApp sessions
• waha_get_session: Get detailed session information
• waha_create_session: Create a new session with configuration
• waha_start_session: Start a stopped session
• waha_stop_session: Stop a running session
• waha_restart_session: Restart a session
• waha_logout_session: Logout and clear authentication
• waha_delete_session: Permanently delete a session
• waha_get_session_me: Get authenticated account info
• waha_get_qr_code: Get QR code for authentication
• waha_request_pairing_code: Request pairing code for phone auth
• waha_get_screenshot: Get session screenshot (WEBJS only)

⏱️ Utility Tools (2 tools)

• sleep: Pause execution for a specified duration (milliseconds or seconds)
• wait: Wait for a specified number of seconds (alias for sleep)

Example: waha_send_poll

Send a poll to a WhatsApp chat with multiple options:

{
  "chatId": "[email protected]",
  "poll": {
    "name": "What's your favorite programming language?",
    "options": ["Python", "JavaScript", "TypeScript", "Go"],
    "multipleAnswers": false
  }
}

Example: waha_create_session

Create a new WhatsApp session with webhook configuration:

{
  "name": "my-session",
  "start": true,
  "config": {
    "webhooks": [{
      "url": "https://your-webhook-url.com",
      "events": ["message", "message.ack", "session.status"]
    }],
    "metadata": {
      "user_id": "123",
      "department": "support"
    }
  }
}

Example: waha_set_my_profile_picture

Update your WhatsApp profile picture:

{
  "file": {
    "url": "https://example.com/my-profile-pic.jpg",
    "mimetype": "image/jpeg"
  }
}

Or using base64:

{
  "file": {
    "data": "iVBORw0KGgoAAAANSUhEUgAAAAUA...",
    "mimetype": "image/png"
  }
}

Example: sleep / wait

Pause execution between operations for rate limiting or automation workflows:

Using sleep with milliseconds:

{
  "duration": 5000,
  "message": "Waiting for rate limit cooldown..."
}

Using sleep with seconds:

{
  "seconds": 3,
  "message": "Pausing between bulk operations"
}

Using wait (alias for sleep):

{
  "seconds": 2,
  "message": "Waiting for user response..."
}

Practical automation example:

1. Send message to contact A
2. Use sleep tool: wait 2 seconds
3. Send message to contact B
4. Use sleep tool: wait 2 seconds
5. Send message to contact C

This prevents rate limiting and makes your automation more natural and human-like.

Project Structure

waha-mcp-server/
├── src/
│   ├── index.ts              # Server entry point
│   ├── config.ts             # Configuration management
│   ├── types/                # TypeScript type definitions
│   ├── tools/                # MCP tool implementations
│   └── client/               # WAHA API client
├── dist/                     # Built JavaScript output
├── .env                      # Your configuration (not in git)
├── .env.example              # Configuration template
├── package.json
├── tsconfig.json
└── PROJECT_SPEC.md          # Full project specification

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