<div align="center"> <img src=".github/logo.png" alt="WAHA MCP Logo" width="200"/>

WAHA MCP Server

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

Documentation • Installation • Configuration • 🤖 Claude Code Setup • Tools Reference </div>

---

🚀 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

<details> <summary><b>Session Management (8 tools)</b></summary>

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

</details>

<details> <summary><b>Authentication (3 tools)</b></summary>

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

</details>

<details> <summary><b>Messaging (14 tools)</b></summary>

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

</details>

<details> <summary><b>Chat Management (7 tools)</b></summary>

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

</details>

<details> <summary><b>Contacts (5 tools)</b></summary>

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

</details>

<details> <summary><b>Groups (13 tools)</b></summary>

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

</details>

<details> <summary><b>Presence & Status (5 tools)</b></summary>

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

</details>

<details> <summary><b>Labels (5 tools)</b></summary>

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

</details>

<details> <summary><b>🆕 Interactive Workflows (1 tool)</b></summary>

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

</details>

---

📚 Chat ID Formats

Understanding WhatsApp ID formats:

Type	Format	Example
User	{phone}@c.us	1234567890@c.us
Group	{id}@g.us	1234567890-1234567890@g.us
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: "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

---

<div align="center">

Built with ❤️ for the MCP community

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

</div>