What is Whatsapp Webjs Mcp Server

whatsapp-webjs-mcp-server is an advanced Model Context Protocol (MCP) server that enables Claude AI to fully control WhatsApp, allowing for messaging, chat management, and more.

Use cases

Use cases include automating customer interactions, sending bulk messages, managing group chats, integrating WhatsApp with AI systems for enhanced communication, and providing real-time notifications.

How to use

To use whatsapp-webjs-mcp-server, follow a simple three-command installation process, configure the MCP settings, and connect your WhatsApp account to start managing messages and contacts seamlessly.

Key features

Key features include auto connection detection, an advanced QR interface, 20 advanced tools for WhatsApp control, full multilingual support, session persistence for long-term use, and a user-friendly installation process.

Where to use

whatsapp-webjs-mcp-server can be used in various fields such as customer support, automated messaging services, personal assistant applications, and any scenario requiring WhatsApp integration.

🚀 WhatsApp Web.js MCP Server

Advanced MCP Server for Complete WhatsApp Control

🎯 What is this?

This is an advanced Model Context Protocol (MCP) server that allows Claude AI to fully control your WhatsApp:

✨ Key Features:

• 🔄 Auto Connection - Detects existing sessions or shows new QR
• 🌐 Advanced QR Interface - Beautiful web interface opens automatically
• 📱 20 Advanced Tools for complete WhatsApp control
• 🌍 Full Multilingual Support - Hebrew RTL, bilingual messages
• 💾 Session Persistence - One-time setup, works forever
• 🚀 Simple as it gets - 3-command installation

📱 System Capabilities

📬 Messaging & Communication

• ✉️ Text Messages with full Unicode support
• 🖼️ Media - Images, videos, audio, documents
• 📝 Media Captions
• 💬 Message Replies to specific messages
• 👤 Mentions (@mentions)
• 🔍 Message Search by text content
• ↗️ Message Forwarding between chats
• 🗑️ Message Deletion (for you or everyone)

💬 Advanced Chat Management

• 📋 Chat Listing (private/groups/all)
• ℹ️ Detailed Chat Info
• 📦 Archive/Unarchive chats
• 📌 Pin/Unpin important chats
• 🔇 Mute/Unmute with custom duration
• ✅ Mark Read/Unread
• 🧹 Clear Messages from chat
• ❌ Delete Chat completely

👥 Contact Management

• 📞 Full Contact List
• 🔍 Search by name or number
• 👤 Detailed Contact Info
• 🚫 Block/Unblock contacts
• 📸 Profile Pictures
• 📄 About/Status Messages
• 👥 Common Groups

🛠️ Quick Installation

System Requirements:

• Node.js 18+
• npm
• Chrome/Chromium (for whatsapp-web.js)

📦 Install in 3 Steps:

# 1. Clone the project
git clone https://github.com/ozlevyq/whatsapp-webjs-mcp-server.git
cd whatsapp-webjs-mcp-server

# 2. Install dependencies
npm install

# 3. Start - That's it!
npm start

Done! 🎉 The system will do everything automatically:

• ✅ Check for existing session
• 🌐 Open browser with QR if needed
• 📱 Connect to WhatsApp
• 🚀 Ready for Claude commands

🔧 MCP Configuration

⚙️ Add to Claude Desktop:

Windows:

{
  "whatsapp": {
    "command": "node",
    "args": [
      "C:\\Users\\YourName\\path\\to\\whatsapp-webjs-mcp-server\\dist\\index.js"
    ]
  }
}

Mac:

{
  "whatsapp": {
    "command": "node",
    "args": [
      "/Users/YourName/path/to/whatsapp-webjs-mcp-server/dist/index.js"
    ]
  }
}

Linux:

{
  "whatsapp": {
    "command": "node",
    "args": [
      "/home/YourName/path/to/whatsapp-webjs-mcp-server/dist/index.js"
    ]
  }
}

📍 Configuration File Locations:

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Mac:

~/Library/Application Support/Claude/claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

🚀 Usage Examples

📱 Send Message:

Send to [email protected]: "Hello! How are you?"

📋 Get Chats:

Show me my chat list

🔍 Search Contact:

Search for contact named "John"

📬 Get Recent Messages:

Get the last 10 messages from the "Friends" group

💬 Manage Chat:

Archive the chat with John
Pin the "Work" group
Mute the chat with Mary for 24 hours

🎨 Advanced QR Interface

When connection is needed, the system:

• 🌐 Opens browser automatically
• 🎨 Shows beautiful multilingual interface
• 🔄 Updates in real-time
• ✅ Notifies when connected successfully

🌟 QR Interface Features:

• Beautiful Design - WhatsApp-style green theme
• Real-time Updates - Auto-refresh every 3 seconds
• Multilingual - English & Hebrew support
• Responsive - Works on desktop and mobile
• Auto-cleanup - QR disappears when connected

🔧 Troubleshooting

❓ Browser doesn’t open?

Open manually: http://localhost:3000

❓ “invalid wid” error?

Use format: [email protected] (private) or [email protected] (groups)

❓ Can’t find chats?

Run first: whatsapp_get_chats to get correct IDs

❓ Session expired?

The system will automatically show new QR code

❓ Connection timeout?

Make sure WhatsApp Web works in your browser first

📋 Available Tools

🚧 Development Status

• ✅ Stable Release - Working excellently
• 🔄 Continuous Development - Regular improvements
• 🆘 Full Support - Available for help
• 🌟 Feature Requests - Always welcome

🛣️ Roadmap:

• [ ] Group administration tools
• [ ] Business account features
• [ ] Message scheduling
• [ ] Bulk operations
• [ ] Analytics and reporting

🤝 Support & Contact

💬 Get Help:

• 🐛 Bug Reports - Open an issue
• 💡 Feature Requests - Start a discussion
• ❓ Questions - Check existing issues or ask
• 🤝 Contributions - Pull requests welcome

📜 License

MIT License - Free to use, share, and modify! 🎉

Copyright (c) 2024 Oz Levy

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

🌟 Contributing

We welcome contributions! Here’s how:

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

🎯 Areas for Contribution:

• 🐛 Bug fixes
• ✨ New features
• 📚 Documentation improvements
• 🌍 Translations
• 🎨 UI/UX enhancements

npm start