WAHA MCP Server

WhatsApp HTTP API integration for Claude Desktop & MCP-compatible clients

Documentation • Installation • Configuration • 🤖 Claude Code Setup • Tools Reference

🚀 What is WAHA MCP?

WAHA MCP Server bridges the powerful WAHA (WhatsApp HTTP API) with AI assistants like Claude Desktop, enabling seamless WhatsApp automation through the Model Context Protocol (MCP).

✨ Key Features

• 📱 Complete WhatsApp Control - Send/receive messages, manage chats, create groups
• 🎯 63 Tools - Comprehensive API coverage for sessions, messaging, contacts, groups, and interactive workflows
• 🔄 Smart Media Handling - Auto-conversion for voice/video, support for URLs & local files
• 🤖 AI-Native - Built specifically for LLM integration via MCP
• 🔒 Secure - Environment-based API key management
• ⚡ Fast & Reliable - TypeScript-powered with robust error handling

📋 Prerequisites

Before you begin, ensure you have:

• Node.js 18+ - Download here
• A running WAHA instance - Setup guide
• WAHA API Key - Generated from your WAHA dashboard

🛠️ Installation

1. Clone & Install

git clone https://github.com/dudu1111685/waha-mcp.git
cd waha-mcp
npm install
npm run build

2. Set Environment Variables

Create a .env file or export variables:

export WAHA_API_KEY="your-api-key-here"
export WAHA_URL="http://localhost:3001"  # Optional, defaults to localhost:3001

⚙️ Configuration

Claude Desktop

Add to claude_desktop_config.json:

Linux: ~/.config/claude/claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "waha": {
      "command": "node",
      "args": ["/absolute/path/to/waha-mcp/dist/index.js"],
      "env": {
        "WAHA_API_KEY": "your-api-key-here",
        "WAHA_URL": "http://localhost:3001"
      }
    }
  }
}

Cline / VS Code

Add to your Cline MCP settings (~/.vscode/mcp.json or workspace settings):

{
  "mcpServers": {
    "waha": {
      "command": "node",
      "args": ["/absolute/path/to/waha-mcp/dist/index.js"],
      "env": {
        "WAHA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code (Autonomous Development)

🤖 Enable truly autonomous AI development:

Instead of Claude stopping when it needs user input, it can ask questions via WhatsApp and continue working!

🚀 Complete Setup Guide: CLAUDE_CODE_SETUP.md

Quick config example:

{
  "mcpServers": {
    "waha": {
      "command": "node",
      "args": ["/path/to/waha-mcp/dist/index.js"],
      "env": {
        "WAHA_API_KEY": "your-key",
        "USER_WHATSAPP_CHAT_ID": "[email protected]"
      }
    }
  },
  "globalInstructions": "When you need user input during development, use ask_user_via_whatsapp tool. Never stop and wait for manual console input."
}

How it works:

1. Claude hits a question → asks via WhatsApp
2. You reply from your phone
3. Claude continues working immediately
4. Zero downtime! ⚡

📖 See also:

• CLAUDE_CODE_SETUP.md - Complete setup guide
• CLAUDE_CODE_INSTRUCTIONS.md - Usage examples for AI assistants

Other MCP Clients

Use the mcporter CLI for quick testing:

mcporter call 'waha-mcp.waha_list_sessions()'
mcporter call 'waha-mcp.waha_send_text(chatId: "[email protected]", text: "Hello from MCP!")'

🧰 Tools Reference

📂 Categories

| Tool | Description | |------|-------------| | waha_list_sessions | List all sessions and their statuses | | waha_get_session | Get detailed info about a session | | waha_create_session | Create a new session | | waha_start_session | Start a stopped session | | waha_stop_session | Stop a running session | | waha_restart_session | Restart a session | | waha_delete_session | Delete a session permanently | | waha_logout_session | Disconnect WhatsApp account from session |

| Tool | Description | |------|-------------| | waha_get_qr_code | Get QR code for WhatsApp authentication | | waha_request_pairing_code | Request phone number pairing code | | waha_check_auth_status | Check session authentication status |

| Tool | Description | |------|-------------| | waha_send_text | Send a text message | | waha_send_image | Send an image (local file or URL) | | waha_send_video | Send a video with auto-conversion | | waha_send_voice | Send a voice message with auto-conversion | | waha_send_file | Send any document/file | | waha_send_location | Send a location pin | | waha_send_contact | Send a contact vCard | | waha_send_poll | Create and send a poll | | waha_react_to_message | React with emoji 👍❤️😂 | | waha_forward_message | Forward a message | | waha_get_messages | Get messages with pagination | | waha_delete_message | Delete a message | | waha_edit_message | Edit a sent message | | waha_mark_as_read | Mark messages as read | | waha_star_message | Star/unstar a message |

📤 Media Upload Features:

• ✅ Local files & URLs supported
• ✅ Auto MIME type detection
• ✅ Auto video/voice conversion to WhatsApp format
• ✅ 50+ file types supported
• ✅ Base64 encoding handled automatically

| Tool | Description | |------|-------------| | waha_list_chats | List all chats | | waha_get_chat | Get detailed chat info | | waha_archive_chat | Archive/unarchive a chat | | waha_pin_chat | Pin/unpin a chat | | waha_mute_chat | Mute/unmute a chat | | waha_delete_chat | Delete a chat | | waha_clear_chat | Clear all messages |

| Tool | Description | |------|-------------| | waha_get_contacts | Get all contacts | | waha_get_contact | Get info about a contact | | waha_check_number_exists | Check if number is on WhatsApp | | waha_block_contact | Block/unblock a contact | | waha_get_profile_picture | Get profile picture URL |

| Tool | Description | |------|-------------| | waha_create_group | Create a new group | | waha_list_groups | List all groups | | waha_get_group | Get detailed group info | | waha_get_group_participants | List group participants | | waha_add_group_participants | Add participants | | waha_remove_group_participants | Remove participants | | waha_promote_group_participant | Promote to admin | | waha_demote_group_participant | Demote from admin | | waha_update_group_subject | Update group name | | waha_update_group_description | Update group description | | waha_update_group_picture | Set group profile picture | | waha_leave_group | Leave a group | | waha_get_group_invite_code | Get invite link | | waha_revoke_group_invite | Revoke & regenerate link |

| Tool | Description | |------|-------------| | waha_set_presence | Set online/offline status | | waha_get_presence | Get contact's presence | | waha_start_typing | Show typing indicator | | waha_stop_typing | Stop typing indicator | | waha_send_status | Post a text status/story |

| Tool | Description | |------|-------------| | waha_get_labels | Get all labels | | waha_create_label | Create a new label | | waha_delete_label | Delete a label | | waha_add_label_to_chat | Add label to chat | | waha_remove_label_from_chat | Remove label from chat |

| Tool | Description | |------|-------------| | ask_user_via_whatsapp | 🚀 NEW! Send a question and WAIT for user reply (blocking operation). Perfect for Claude Code workflows that need user input mid-execution. |

Use Case Example:

// Claude Code is building a feature and needs clarification
const reply = await ask_user_via_whatsapp({
  question: "Should I use REST or GraphQL for the API?",
  chatId: "[email protected]",
  timeoutMinutes: 30
});
// User replies from phone: "Use GraphQL"
// Claude Code continues with GraphQL implementation

How it works:

1. Sends your question via WhatsApp
2. Polls for new messages from the user
3. Returns the reply text when received
4. Includes timeout handling (default: 60 minutes)

Perfect for:

• 🤖 Claude Code asking questions mid-workflow
• 💡 Getting user input while you're away from the computer
• 🔄 Building truly interactive AI automations
• 📱 Answering from your phone while AI continues working

📚 Chat ID Formats

Understanding WhatsApp ID formats:

| Type | Format | Example | |------|--------|---------| | User | {phone}@c.us | [email protected] | | Group | {id}@g.us | [email protected] | | Channel | {id}@newsletter | 1234567890@newsletter | | Status | status@broadcast | status@broadcast |

Note: Phone numbers should exclude the + prefix.

🎯 Quick Examples

Send a Text Message

mcporter call 'waha-mcp.waha_send_text(
  chatId: "[email protected]",
  text: "Hello from WAHA MCP!"
)'

Send an Image from URL

mcporter call 'waha-mcp.waha_send_image(
  chatId: "[email protected]",
  imageUrl: "https://example.com/photo.jpg",
  caption: "Check this out!"
)'

Create a Group & Add Participants

# Create group
mcporter call 'waha-mcp.waha_create_group(
  name: "Team Chat",
  participants: ["[email protected]", "[email protected]"]
)'

# Add more participants
mcporter call 'waha-mcp.waha_add_group_participants(
  chatId: "{group_id}@g.us",
  participants: ["[email protected]"]
)'

List All Chats

mcporter call 'waha-mcp.waha_list_chats()'

🧪 Development

Run in Watch Mode

npm run dev  # Recompiles on file changes

Run Tests

npm test

Build for Production

npm run build

📖 Documentation

For detailed documentation, see the docs folder:

• Session Management
• Messaging Guide
• Group Management
• Media Handling
• Troubleshooting

🤝 Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• WAHA (WhatsApp HTTP API) - The backbone of this integration
• Model Context Protocol - Enabling AI-native tool integration
• Anthropic - For Claude Desktop and MCP SDK

Built with ❤️ for the MCP community

⭐ Star this repo • 🐛 Report Bug • 💡 Request Feature