Which integrations are available for this server?

Provides comprehensive tools for automating WhatsApp accounts via the WAHA HTTP API, including messaging (text, media, polls), chat and group management, contact interactions, and real-time presence control.

How do I use WAHA MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@WAHA MCP Server Send a WhatsApp message to 1234567890@c.us saying the report is ready" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

WAHA MCP Server

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

License: MIT Node.js Version MCP Compatible TypeScript

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:

Claude hits a question → asks via WhatsApp
You reply from your phone
Claude continues working immediately
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

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: "1234567890@c.us", timeoutMinutes: 30 }); // User replies from phone: "Use GraphQL" // Claude Code continues with GraphQL implementation

How it works:

Sends your question via WhatsApp
Polls for new messages from the user
Returns the reply text when received
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`	`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:

🤝 Contributing

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

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

WAHA MCP Server

WAHA MCP Server

🚀 What is WAHA MCP?

✨ Key Features

📋 Prerequisites

🛠️ Installation

1. Clone & Install

2. Set Environment Variables

⚙️ Configuration

Claude Desktop

Cline / VS Code

Claude Code (Autonomous Development)

Other MCP Clients

🧰 Tools Reference

📂 Categories

📚 Chat ID Formats

🎯 Quick Examples

Send a Text Message

Send an Image from URL

Create a Group & Add Participants

List All Chats

🧪 Development

Run in Watch Mode

Run Tests

Build for Production

📖 Documentation

🤝 Contributing

📄 License

🙏 Acknowledgments

Resources

Tools

New MCP Servers

Latest Blog Posts

MCP directory API