WhatsApp Web MCP

A robust conduit linking the WhatsApp Web environment to advanced computational intelligence models leveraging the Model Context Protocol (MCP). This utility enables large language models, such as Claude, to interface programmatically with WhatsApp through a strictly defined interface, facilitating automation and refinement of messaging workflows.

Core Concepts

WhatsApp Web MCP establishes a frictionless connection between the WhatsApp Web client and AI engines by: - Establishing a canonical interface blueprint through the Model Context Protocol (MCP). - Exposing MCP Server access points to core WhatsApp operational features. - Offering elastic deployment configurations via Server-Sent Events (SSE) or direct Command execution modes. - Facilitating connectivity through direct client embedding or intermediate API pathways.

Caveats

CRITICAL NOTICE: This instrument is strictly designated for validation and experimental operation; deployment in live, production ecosystems is strongly discouraged.

Official stance from the WhatsApp Web initiative:

This utility holds no official affiliation, association, authorization, endorsement, or structural connection to WhatsApp or any of its subsidiaries or associated entities. The legitimate web presence for WhatsApp is maintained at whatsapp.com. The nomenclature "WhatsApp," alongside associated graphical elements, proprietary markings, and emblems, constitutes registered intellectual property belonging to their respective proprietors. Furthermore, there is no guarantee against potential service suspension or account termination resulting from the utilization of this methodology. As WhatsApp explicitly prohibits automated agents or non-sanctioned client applications on its platform, this approach should not be deemed entirely secure or risk-free.

Deployment Procedure

1. Obtain the source code repository: bash git clone https://github.com/pnizer/wweb-mcp.git cd wweb-mcp

2. Install system-wide or invoke via npx: bash # Global Installation npm install -g .

# Direct invocation using npx npx .

1. Containerize using Docker: bash docker build . -t wweb-mcp:latest

Parameterization Directives

Command Line Arguments

Flag	Shorthand	Purpose	Permissible Values	Default Setting
--mode	-m	Operational regime selection	mcp, whatsapp-api	mcp
--mcp-mode	-c	MCP operational configuration	standalone, api	standalone
--transport	-t	MCP data conveyance method	sse, command	sse
--sse-port	-p	Network port dedicated to the SSE interface	N/A	3002
--api-port	-	Network port for the WhatsApp API service	N/A	3001
--auth-data-path	-a	Directory path to cache authentication artifacts	N/A	.wwebjs_auth
--auth-strategy	-s	Mechanism employed for user authentication	local, none	local
--api-base-url	-b	Root URL endpoint for the MCP when operating in API mode	N/A	http://localhost:3001/api
--api-key	-k	Security credential for the WhatsApp Web REST interface (API mode)	N/A	''

REST API Credentialing

When configured for API mode, the WhatsApp API service mandates credential validation via a secret API key. This key is algorithmically generated upon the initial launch of the WhatsApp API service and is prominently displayed within the console output:

WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

To establish a link between the MCP server and the WhatsApp API service, this retrieved security key must be supplied using either the --api-key or -k directive:

bash npx wweb-mcp --mode mcp --mcp-mode api --api-base-url http://localhost:3001/api --api-key 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

The API access key is persistently stored within the authentication data volume (designated by --auth-data-path) and remains valid across subsequent restarts of the WhatsApp API service.

User Verification Methods

Local Persistence (Recommended Approach)

• Initial interaction requires a single QR code scan.
• Session credentials are retained across subsequent operational cycles.
• Offers superior stability for protracted operational periods.

Zero Verification

• The default operational schema.
• Mandates a fresh QR code presentation upon every application launch.
• Best suited for iterative development and momentary testing.

Operational Examples

Execution Regimes

WhatsApp Service Host

Initiates a self-contained RESTful API service encapsulating WhatsApp functionality: bash npx wweb-mcp --mode whatsapp-api --api-port 3001

MCP Host (Independent Configuration)

Launches an MCP server that establishes a direct link to the WhatsApp Web interface: bash npx wweb-mcp --mode mcp --mcp-mode standalone --transport sse --sse-port 3002

MCP Host (API Client Configuration)

Deploys an MCP server configured to interface with the separate WhatsApp API service: bash

Phase 1: Activate the WhatsApp API service and record the resultant API key

npx wweb-mcp --mode whatsapp-api --api-port 3001

Phase 2: Activate the MCP server, supplying the necessary API credential

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

Callable Functions (Tools)

Function Name	Purpose	Input Signatures
get_status	Query the connection fidelity of the WhatsApp client	No Inputs
send_message	Transmit a textual payload to a designated recipient	number: Target identifier message: String payload content
search_contacts	Locate entries within the address book based on identifiers or names	query: Search criteria string
get_messages	Fetch recent message history from a specific dialogue thread	number: Dialogue participant identifier limit (optional): Constraint on record count
get_chats	Retrieve a catalogue of all active conversations	No Inputs
create_group	Provision a novel group entity	name: Designation for the new group participants: Collection of initiating phone numbers
add_participants_to_group	Onboard supplementary members into an established group	groupId: Unique identifier of the cohort participants: Collection of identifiers to be added
get_group_messages	Retrieve message archives from a specific group entity	groupId: Unique cohort identifier limit (optional): Record count threshold
send_group_message	Broadcast a textual message across a group channel	groupId: Unique cohort identifier message: String payload content
search_groups	Execute a query against group metadata (names, descriptions, members)	query: Search string
get_group_by_id	Obtain comprehensive metadata for a specified group	groupId: Unique cohort identifier

Accessible Data Endpoints (Resources)

URI Path	Description
whatsapp://contacts	Manifest of all registered user contacts
whatsapp://messages/{number}	Chronological message sequence for an individual chat
whatsapp://chats	Index of all currently active communication threads
whatsapp://groups	Index of all extant group entities
whatsapp://groups/search	Interface for querying group metadata
whatsapp://groups/{groupId}/messages	Chronological message sequence within a specific cohort

External RESTful Interface Definitions

Dialogue Management & Message Retrieval

Endpoint	Method	Summary	Arguments
/api/status	GET	Determine current operational readiness	None
/api/contacts	GET	Fetch entire contact registry	None
/api/contacts/search	GET	Filter contacts by criteria	query: Search parameter
/api/chats	GET	Retrieve all chat summaries	None
/api/messages/{number}	GET	Retrieve dialogue history	limit (query): Maximum message count
/api/send	POST	Dispatch a message	number: Destination ID message: Textual body

Cohort Administration

Endpoint	Method	Summary	Arguments
/api/groups	GET	List all managed group entities	None
/api/groups/search	GET	Search group records	query: Search parameter
/api/groups/create	POST	Provision a new group	name: Group designation participants: Array of participant identifiers
/api/groups/{groupId}	GET	Retrieve detailed group profile	None
/api/groups/{groupId}/messages	GET	Fetch group message history	limit (query): Message count cap
/api/groups/{groupId}/participants/add	POST	Introduce new members	participants: Array of identifiers
/api/groups/send	POST	Broadcast to a group	groupId: Cohort ID message: Textual body

AI Integration Protocols

Claude Desktop Interoperability

Method A: Utilizing NPX Invocation

1. Initialize the WhatsApp API service host: bash npx wweb-mcp -m whatsapp-api -s local

2. Authenticate by scanning the presented QR code using your mobile WhatsApp application.

3. Log the security credential outputted:

WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

1. Augment your Claude Desktop configuration file with the following structure:

{ "mcpServers": { "whatsapp": { "command": "npx", "args": [ "wweb-mcp", "-m", "mcp", "-s", "local", "-c", "api", "-t", "command", "--api-base-url", "http://localhost:3001/api", "--api-key", "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" ] } } }

Method B: Employing Docker Containers

1. Launch the WhatsApp API service host within a Docker context: bash docker run -i -p 3001:3001 -v wweb-mcp:/wwebjs_auth --rm wweb-mcp:latest -m whatsapp-api -s local -a /wwebjs_auth

2. Authenticate via QR code scan.

3. Capture the displayed API security token:

WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

1. Update your Claude Desktop configuration with this containerized definition:

{ "mcpServers": { "whatsapp": { "command": "docker", "args": [ "run", "-i", "--rm", "wweb-mcp:latest", "-m", "mcp", "-s", "local", "-c", "api", "-t", "command", "--api-base-url", "http://host.docker.internal:3001/api", "--api-key", "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" ] } } }

1. Relaunch the Claude Desktop application.
2. WhatsApp functionalities will subsequently be accessible through the Claude user interface stratum.

Structural Blueprint

The codebase organization emphasizes a clear division of functional responsibilities:

Constituent Modules

1. WhatsAppService: Centralized management of WhatsApp operational logic.
2. WhatsAppApiClient: Interface client responsible for external WhatsApp API communication.
3. API Router: Express-based routing layer for the REST interface.
4. MCP Server: Implementation layer conforming to the Model Context Protocol specification.

Deployment Modalities

1. WhatsApp API Host: Deployed as a standalone RESTful service.
2. MCP Host (Independent): Utilizes a direct communication pathway to WhatsApp Web.
3. MCP Host (API Client): Operates as a client module communicating with a pre-existing API Host.

This design promotes adaptability across various deployment topologies, such as: - Separation of the API service and MCP server onto distinct computational nodes. - Configuration of the MCP server to leverage an external, already operational API service. - Consolidation of all services onto a singular host for enhanced simplicity.

Engineering Procedures

Directory Layout

src/ ├── whatsapp-client.ts # Implements the WhatsApp Web client interaction logic ├── whatsapp-service.ts # Encapsulates core business routines ├── whatsapp-api-client.ts # Client logic for interfacing with the WhatsApp API ├── api.ts # Defines and manages the REST API routing structure ├── mcp-server.ts # Handles the MCP protocol translation layer └── main.ts # Application bootstrap sequence

Compilation from Source

bash npm run build

Verification Suites

The project employs Jest for its comprehensive unit testing framework. Execution is initiated via:

bash

Execute all defined tests

npm test

Activate continuous testing mode during development

npm run test:watch

Generate a report detailing test coverage metrics

npm run test:coverage

Code Quality Assurance

ESLint and Prettier are utilized to enforce standardized code styling and quality:

bash

Execute static analysis checks

npm run lint

Attempt automatic correction of stylistic violations

npm run lint:fix

Apply Prettier formatting rules across the codebase

npm run format

Comprehensive validation check (linting + testing)

npm run validate

The linting configuration is tuned to uphold best practices specific to TypeScript and maintain stylistic coherence throughout the repository.

Diagnostic Assistance

Issues with Claude Desktop Integration

• A known constraint prevents running wweb-mcp in standalone command mode within the Claude execution environment. This is due to Claude launching multiple, ephemeral processes, each attempting to initialize a Puppeteer session that cannot safely share the WhatsApp authentication state. To circumvent this, the application is bifurcated into distinct MCP and API operational modes suitable for Claude's interaction model.

Future Enhancements

• Implementation of event-driven webhooks for real-time delivery notifications and status changes.
• Capability to transmit non-textual payloads (e.g., visual media, audio files, documentation).
• Advanced tooling for group configuration and administration.
• Functionality for contact record management (addition/removal).
• Pre-defined message scripting tools for routine communications.
• Refinements to error detection mechanisms and automated recovery protocols.

Collaborative Input

1. Create a derivative copy of the repository (Fork).
2. Establish a dedicated branch for your intended feature enhancement.
3. Document your modifications via commit messages.
4. Push the resulting commits to your derived branch.
5. Submit a formal Pull Request (PR).

Please ensure your submitted PR adheres to these guidelines: - Conformity with the prevailing code conventions. - Inclusion of adequate test coverage for new functionality. - Necessary updates to all relevant documentation sections. - A clear, detailed narrative explaining the implemented changes.

Component Dependencies

reliance on WhatsApp Web.js

This project is architected upon whatsapp-web.js, which functions as an unauthorized JavaScript client library interfacing with the WhatsApp Web browser application. Further insight into this underlying technology is available at the whatsapp-web.js GitHub repository.

Licensing Terms

This software asset is distributed under the terms of the MIT License; consult the accompanying LICENSE file for explicit provisions.

Observability and Logging

WhatsApp Web MCP incorporates a sophisticated logging framework built upon Winston, offering the following features:

• Tiered log severity levels (error, warn, info, http, debug).
• Console output featuring syntax highlighting.
• Logging integration for HTTP request/response cycles associated with API routes.
• Uniform structuring for error data representation.
• Log verbosity scaling based on the execution environment (development versus production).
• In MCP command execution mode (--transport command), all diagnostic output is strictly routed to stderr.

Severity Tiers

The system supports logging across these distinct levels, ordered by increasing detail:

1. error: Failures that halt critical application operations.
2. warn: Conditions warranting attention but not causing immediate operational cessation.
3. info: General status updates and significant event reporting.
4. http: Tracing of all inbound and outbound HTTP communications.
5. debug: Highly granular data intended for deep diagnostic tracing.

Modifying Verbosity

The logging output threshold can be adjusted during initialization via the --log-level or -l argument:

bash npm start -- --log-level=debug

Or when invoking the globally installed binary:

bash wweb-mcp --log-level=debug

Command Mode Specifics

When operating in MCP command mode (--mode mcp --transport command), all log streams are directed exclusively to stderr. This segregation is intentional, ensuring that stdout remains clear for the structured output required by the MCP protocol itself, thereby preventing contamination of inter-process communication by diagnostic messages.

Testing Environment Posture

When the environment variable NODE_ENV is set to test or when using the Jest runner, the logger automatically configures itself for optimal testing conditions.