Waha MCP

🚀 WAHA MCP Server

Integrate WhatsApp HTTP API with Claude Desktop and MCP-compatible clients for seamless WhatsApp automation.

🚀 Quick Start

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).

✨ 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:

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:

• - Complete setup guide.
• - 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

// 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

📚 Chat ID Formats

Understanding WhatsApp ID formats:

⚠️ Important Note

Phone numbers should exclude the + prefix.

💻 Usage 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.