WAHA MCP Server

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": "1234567890@c.us"
      }
    }
  },
  "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: "1234567890@c.us", text: "Hello from MCP!")'

🧰 Tools Reference

📂 Categories