WhatsApp Web MCP
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Integrations
Provides a bridge to WhatsApp Web functionality, enabling tools to send/receive messages, search contacts, manage groups, retrieve chat histories, and perform other WhatsApp operations programmatically.
WhatsApp Web MCP
A powerful bridge between WhatsApp Web and AI models using the Model Context Protocol (MCP). This project enables AI models like Claude to interact with WhatsApp through a standardized interface, making it easy to automate and enhance WhatsApp interactions programmatically.
Overview
WhatsApp Web MCP provides a seamless integration between WhatsApp Web and AI models by:
- Creating a standardized interface through the Model Context Protocol (MCP)
- Offering MCP Server access to WhatsApp functionality
- Providing flexible deployment options through SSE or Command modes
- Supporting both direct WhatsApp client integration and API-based connectivity
Disclaimer
IMPORTANT: This tool is for testing purposes only and should not be used in production environments.
Disclaimer from WhatsApp Web project:
This project is not affiliated, associated, authorized, endorsed by, or in any way officially connected with WhatsApp or any of its subsidiaries or its affiliates. The official WhatsApp website can be found at whatsapp.com. "WhatsApp" as well as related names, marks, emblems and images are registered trademarks of their respective owners. Also it is not guaranteed you will not be blocked by using this method. WhatsApp does not allow bots or unofficial clients on their platform, so this shouldn't be considered totally safe.
Installation
- Clone the repository:Copy
- Install globally or use with npx:Copy
- Build with Docker:Copy
Configuration
Command Line Options
| Option | Alias | Description | Choices | Default |
|---|---|---|---|---|
--mode | -m | Run mode | mcp, whatsapp-api | mcp |
--mcp-mode | -c | MCP connection mode | standalone, api | standalone |
--transport | -t | MCP transport mode | sse, command | sse |
--sse-port | -p | Port for SSE server | - | 3002 |
--api-port | - | Port for WhatsApp API server | - | 3001 |
--auth-data-path | -a | Path to store authentication data | - | .wwebjs_auth |
--auth-strategy | -s | Authentication strategy | local, none | local |
--api-base-url | -b | API base URL for MCP when using api mode | - | http://localhost:3001/api |
--api-key | -k | API key for WhatsApp Web REST API when using api mode | - | '' |
API Key Authentication
When running in API mode, the WhatsApp API server requires authentication using an API key. The API key is automatically generated when you start the WhatsApp API server and is displayed in the logs:
To connect the MCP server to the WhatsApp API server, you need to provide this API key using the --api-key or -k option:
The API key is stored in the authentication data directory (specified by --auth-data-path) and persists between restarts of the WhatsApp API server.
Authentication Methods
Local Authentication (Recommended)
- Scan QR code once
- Credentials persist between sessions
- More stable for long-term operation
No Authentication
- Default method
- Requires QR code scan on each startup
- Suitable for testing and development
Usage
Running Modes
WhatsApp API Server
Run a standalone WhatsApp API server that exposes WhatsApp functionality through REST endpoints:
MCP Server (Standalone)
Run an MCP server that directly connects to WhatsApp Web:
MCP Server (API Client)
Run an MCP server that connects to the WhatsApp API server:
Available Tools
| Tool | Description | Parameters |
|---|---|---|
get_status | Check WhatsApp client connection status | None |
send_message | Send messages to WhatsApp contacts | number: Phone number to send tomessage: Text content to send |
search_contacts | Search for contacts by name or number | query: Search term to find contacts |
get_messages | Retrieve messages from a specific chat | number: Phone number to get messages fromlimit (optional): Number of messages to retrieve |
get_chats | Get a list of all WhatsApp chats | None |
create_group | Create a new WhatsApp group | name: Name of the groupparticipants: Array of phone numbers to add |
add_participants_to_group | Add participants to an existing group | groupId: ID of the groupparticipants: Array of phone numbers to add |
get_group_messages | Retrieve messages from a group | groupId: ID of the grouplimit (optional): Number of messages to retrieve |
send_group_message | Send a message to a group | groupId: ID of the groupmessage: Text content to send |
search_groups | Search for groups by name, description, or member names | query: Search term to find groups |
get_group_by_id | Get detailed information about a specific group | groupId: ID of the group to get |
Available Resources
| Resource URI | Description |
|---|---|
whatsapp://contacts | List of all WhatsApp contacts |
whatsapp://messages/{number} | Messages from a specific chat |
whatsapp://chats | List of all WhatsApp chats |
whatsapp://groups | List of all WhatsApp groups |
whatsapp://groups/search | Search for groups by name, description, or member names |
whatsapp://groups/{groupId}/messages | Messages from a specific group |
REST API Endpoints
Contacts & Messages
| Endpoint | Method | Description | Parameters |
|---|---|---|---|
/api/status | GET | Get WhatsApp connection status | None |
/api/contacts | GET | Get all contacts | None |
/api/contacts/search | GET | Search for contacts | query: Search term |
/api/chats | GET | Get all chats | None |
/api/messages/{number} | GET | Get messages from a chat | limit (query): Number of messages |
/api/send | POST | Send a message | number: Recipientmessage: Message content |
Group Management
| Endpoint | Method | Description | Parameters |
|---|---|---|---|
/api/groups | GET | Get all groups | None |
/api/groups/search | GET | Search for groups | query: Search term |
/api/groups/create | POST | Create a new group | name: Group nameparticipants: Array of numbers |
/api/groups/{groupId} | GET | Get detailed information about a specific group | None |
/api/groups/{groupId}/messages | GET | Get messages from a group | limit (query): Number of messages |
/api/groups/{groupId}/participants/add | POST | Add members to a group | participants: Array of numbers |
/api/groups/send | POST | Send a message to a group | groupId: Group IDmessage: Message content |
AI Integration
Claude Desktop Integration
Option 1: Using NPX
- Start WhatsApp API server:Copy
- Scan the QR code with your WhatsApp mobile app
- Note the API key displayed in the logs:Copy
- Add the following to your Claude Desktop configuration:Copy
Option 2: Using Docker
- Start WhatsApp API server in Docker:Copy
- Scan the QR code with your WhatsApp mobile app
- Note the API key displayed in the logs:Copy
- Add the following to your Claude Desktop configuration:Copy
- Restart Claude Desktop
- The WhatsApp functionality will be available through Claude's interface
Architecture
The project is structured with a clean separation of concerns:
Components
- WhatsAppService: Core business logic for interacting with WhatsApp
- WhatsAppApiClient: Client for connecting to the WhatsApp API
- API Router: Express routes for the REST API
- MCP Server: Model Context Protocol implementation
Deployment Options
- WhatsApp API Server: Standalone REST API server
- MCP Server (Standalone): Direct connection to WhatsApp Web
- MCP Server (API Client): Connection to WhatsApp API server
This architecture allows for flexible deployment scenarios, including:
- Running the API server and MCP server on different machines
- Using the MCP server as a client to an existing API server
- Running everything on a single machine for simplicity
Development
Project Structure
Building from Source
Testing
The project uses Jest for unit testing. To run the tests:
Linting and Formatting
The project uses ESLint and Prettier for code quality and formatting:
The linting configuration enforces TypeScript best practices and maintains consistent code style across the project.
Troubleshooting
Claude Desktop Integration Issues
- It's not possible to start wweb-mcp in command standalone mode on Claude because Claude opens more than one process, multiple times, and each wweb-mcp needs to open a puppeteer session that cannot share the same WhatsApp authentication. Because of this limitation, we've split the app into MCP and API modes to allow for proper integration with Claude.
Upcoming Features
- Create webhooks for incoming messages and other WhatsApp events
- Support for sending media files (images, audio, documents)
- Group chat management features
- Contact management (add/remove contacts)
- Message templates for common scenarios
- Enhanced error handling and recovery
Contributing
- Fork the repository
- Create a feature branch
- Commit your changes
- Push to your branch
- Create a Pull Request
Please ensure your PR:
- Follows the existing code style
- Includes appropriate tests
- Updates documentation as needed
- Describes the changes in detail
Dependencies
WhatsApp Web.js
This project uses whatsapp-web.js, an unofficial JavaScript client library for WhatsApp Web that connects through the WhatsApp Web browser app. For more information, visit the whatsapp-web.js GitHub repository.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Logging
WhatsApp Web MCP includes a robust logging system built with Winston. The logging system provides:
- Multiple log levels (error, warn, info, http, debug)
- Console output with colorized logs
- HTTP request/response logging for API endpoints
- Structured error handling
- Environment-aware log levels (development vs. production)
- All logs directed to stderr when running in MCP command mode
Log Levels
The application supports the following log levels, in order of verbosity:
- error - Critical errors that prevent the application from functioning
- warn - Warnings that don't stop the application but require attention
- info - General information about application state and events
- http - HTTP request/response logging
- debug - Detailed debugging information
Configuring Log Level
You can configure the log level when starting the application using the --log-level or -l flag:
Or when using the global installation:
Command Mode Logging
When running in MCP command mode (--mode mcp --transport command), all logs are directed to stderr. This is important for command-line tools where stdout might be used for data output while stderr is used for logging and diagnostics. This ensures that the MCP protocol communication over stdout is not interfered with by log messages.
Test Environment
In test environments (when NODE_ENV=test or when running with Jest), the logger automatically adjusts its behavior to be suitable for testing environments.
This server cannot be installed
A bridge that connects WhatsApp Web to AI models using the Model Context Protocol, enabling Claude and other AI systems to interact with WhatsApp through a standardized interface.