A Node.js application that connects WhatsApp Web with AI models through the Model Context Protocol (MCP). This project provides a standardized interface for programmatic interaction with WhatsApp, enabling automated messaging, contact management, and group chat functionality through AI-driven workflows.
Overview
WhatsApp Web MCP Server
ดาว
46
เครื่องมือ
—
อัปไทม์
—
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.
Learning Resources
To learn more about using WhatsApp Web MCP in real-world scenarios, check out these articles:
git clone https://github.com/pnizer/wweb-mcp.git
cd wweb-mcp
Install globally or use with npx:
# Install globally
npm install -g .
# Or use with npx directly
npx .
Build with Docker:
docker build . -t wweb-mcp:latest
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:
WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
To connect the MCP server to the WhatsApp API server, you need to provide this API key using the --api-key or -k option:
npx wweb-mcp --mode mcp --mcp-mode api --api-base-url http://localhost:3001/api --api-key 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
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
Webhook Configuration
You can configure webhooks to receive incoming WhatsApp messages by creating a webhook.json file in your authentication data directory (specified by --auth-data-path).
Run an MCP server that connects to the WhatsApp API server:
# First, start the WhatsApp API server and note the API key from the logs
npx wweb-mcp --mode whatsapp-api --api-port 3001
# Then, start the MCP server with the API key
npx wweb-mcp --mode mcp --mcp-mode api --api-base-url http://localhost:3001/api --api-key YOUR_API_KEY --transport sse --sse-port 3002
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
download_media_from_message
Download media from a message
messageId: ID of the message containing media to download
send_media_message
Send a media message to a WhatsApp contact
number: Phone number to send tosource: Media source with URI scheme (use http:// or https:// for URLs, file:// for local files)caption (optional): Text caption for the media
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
/api/send/media
POST
Send a media message
number: Recipientsource: Media source with URI scheme (use http:// or https:// for URLs, file:// for local files)caption (optional): Text caption
/api/messages/{messageId}/media/download
POST
Download media from a message
None
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:
npx wweb-mcp -m whatsapp-api -s local
Scan the QR code with your WhatsApp mobile app
Note the API key displayed in the logs:
WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
Add the following to your Claude Desktop configuration:
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
src/
├── whatsapp-client.ts # WhatsApp Web client implementation
├── whatsapp-service.ts # Core business logic
├── whatsapp-api-client.ts # Client for the WhatsApp API
├── api.ts # REST API router
├── mcp-server.ts # MCP protocol implementation
└── main.ts # Application entry point
Building from Source
npm run build
Testing
The project uses Jest for unit testing. To run the tests:
# Run all tests
npm test
# Run tests in watch mode during development
npm run test:watch
# Generate test coverage report
npm run test:coverage
Linting and Formatting
The project uses ESLint and Prettier for code quality and formatting:
# Run linter
npm run lint
# Fix linting issues automatically
npm run lint:fix
# Format code with Prettier
npm run format
# Validate code (lint + test)
npm run validate
The linting configuration enforces TypeScript best practices and maintains consistent code style across the project.
Publishing
The project uses GitHub Actions for automated publishing to npm. The workflow handles:
Version incrementing (patch, minor, or major)
Git tagging with version prefixed by 'v' (e.g., v0.2.1)
Publishing to npm with GitHub secrets
To release a new version:
Go to the GitHub repository Actions tab
Select the "Publish Package" workflow
Click "Run workflow"
Choose the version increment type (patch, minor, or major)
Click "Run workflow" to start the publishing process
This workflow requires an NPM_TOKEN secret to be configured in your GitHub repository.
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.
Features
Sending and receiving messages
Sending media messages (images only)
Downloading media from messages (images, audio, documents)
Group chat management
Contact management and search
Message history retrieval
Upcoming Features
Support for sending all media file types (video, audio, documents)
Enhanced message templates for common scenarios
Advanced group management features
Contact management (add/remove contacts)
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:
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:
npm start -- --log-level=debug
Or when using the global installation:
wweb-mcp --log-level=debug
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.