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

📤 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

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: "1234567890@c.us",
  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:

Note: Phone numbers should exclude the + prefix.

🎯 Quick Examples

Send a Text Message

mcporter call 'waha-mcp.waha_send_text(
  chatId: "1234567890@c.us",
  text: "Hello from WAHA MCP!"
)'

Send an Image from URL

mcporter call 'waha-mcp.waha_send_image(
  chatId: "1234567890@c.us",
  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: ["1111111111@c.us", "2222222222@c.us"]
)'

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

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