WhatsApp Web MCP Orchestrator

A robust intermediary connecting WhatsApp Web capabilities with sophisticated Artificial Intelligence engines through the formal Model Context Protocol (MCP) specification. This utility enables AI agents, such as Claude, to manipulate WhatsApp functions via a standardized gateway, simplifying the automation and refinement of conversational exchanges programmatically.

Conceptual Summary

This Orchestrator establishes a frictionless conduit between the WhatsApp Web client and external AI models by: - Establishing a defined communication standard using the Model Context Protocol (MCP). - Exposing MCP Server access points to leverage core WhatsApp operations. - Supporting heterogeneous deployment paradigms via Server-Sent Events (SSE) or direct Command invocation methods. - Accommodating both direct browser integration and abstracted API-driven connectivity.

Legal Stipulations

CRITICAL NOTICE: This utility is strictly intended for experimental validation and must not be deployed in live production ecosystems.

Official statement from the WhatsApp Web project maintainers:

We disclaim any affiliation, association, authorization, endorsement, or formal connection with WhatsApp or any of its subsidiaries or affiliated entities. The official domain for WhatsApp is whatsapp.com. The term "WhatsApp," along with associated trademarks, symbols, and imagery, are the registered property of their respective proprietors. Furthermore, we offer no assurance against account suspension resulting from this methodology. As WhatsApp explicitly prohibits automated or non-sanctioned client interfaces, this approach carries inherent risk.

Setup Procedure

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

2. Install globally for system-wide access or execute via NPX: bash # Global Installation npm install -g .

# Direct Execution via NPX npx .

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

Parameterization Directives

Command Line Modifiers

Parameter	Shorthand	Purpose	Valid Selections	Default Value
--mode	-m	Operational execution scheme	mcp, whatsapp-api	mcp
--mcp-mode	-c	MCP communication topology	standalone, api	standalone
--transport	-t	MCP data transfer mechanism	sse, command	sse
--sse-port	-p	TCP port for the SSE conduit	N/A	3002
--api-port	-	TCP port reserved for the WhatsApp Gateway service	N/A	3001
--auth-data-path	-a	Directory location for persistence of authentication artifacts	N/A	.wwebjs_auth
--auth-strategy	-s	Methodology employed for credential handling	local, none	local
--api-base-url	-b	Base URI for MCP when operating in API client configuration	N/A	http://localhost:3001/api
--api-key	-k	Security token required for RESTful WhatsApp Gateway access	N/A	''

Gateway Token Security

When utilizing the API operational scheme, the WhatsApp Gateway necessitates cryptographic verification via an API Key. This key is algorithmically generated upon the initial launch of the Gateway service and explicitly logged:

WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

To establish the MCP server's secure linkage with the WhatsApp Gateway, this token must be supplied using the --api-key or -k argument:

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

The API credential is persistently stored within the designated authentication data volume (set by --auth-data-path) ensuring continuity across subsequent Gateway service restarts.

Credential Handling Modalities

Local Credential Storage (Recommended)

• Initiation requires a single QR code scan.
• Session credentials survive subsequent service shutdowns and restarts.
• Offers superior reliability for sustained operation.

Unauthenticated Mode

• Default configuration.
• Mandates re-scanning the QR code upon every initialization.
• Appropriate only for initial development and brief testing cycles.

Operational Use Cases

Execution Schemas

WhatsApp Gateway Service

Initiate a detached, self-contained WhatsApp Gateway exposing functionality via HTTP endpoints: bash npx wweb-mcp --mode whatsapp-api --api-port 3001

MCP Server (Independent Mode)

Launch an MCP server that forges a direct linkage with the WhatsApp Web instance: bash npx wweb-mcp --mode mcp --mcp-mode standalone --transport sse --sse-port 3002

MCP Server (Gateway Client)

Configure an MCP server to communicate solely with the prerequisite WhatsApp Gateway service: bash

Step 1: Launch the WhatsApp Gateway and capture the generated API Key from the console output

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

Step 2: Initiate the MCP client, supplying the captured 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 Action Interfaces (Tools)

Interface	Purpose	Required Arguments	Optional Arguments
get_status	Assess the connectivity state of the WhatsApp client	None	None
send_message	Dispatch textual payloads to specific recipients	number: Target identifier message: Message body content	None
search_contacts	Query contact directory based on identifying strings	query: Search criterion	None
get_messages	Fetch historical data from a defined chat thread	number: Chat identifier limit: Maximum record count	limit
get_chats	Retrieve an aggregated index of all active conversations	None	None
create_group	Provision a novel group entity	name: Designator for the group participants: List of numerical identifiers to include	None
add_participants_to_group	Incorporate new members into an existing group	groupId: Unique group identifier participants: List of numerical identifiers	None
get_group_messages	Retrieve message logs specific to a group	groupId: Group unique identifier limit: Maximum record count	limit
send_group_message	Dispatch textual payloads to a group entity	groupId: Group unique identifier message: Message body content	None
search_groups	Locate groups via name, descriptor, or member listings	query: Search term	None
get_group_by_id	Obtain comprehensive metadata for a specified group	groupId: Group unique identifier	None

Accessible Data Uniform Resource Identifiers (URIs)

URI Pattern	Description
whatsapp://contacts	Enumeration of all registered WhatsApp contacts
whatsapp://messages/{number}	Chronological message sequence for a given dialogue
whatsapp://chats	Index of all active chat sessions
whatsapp://groups	Directory of all established group entities
whatsapp://groups/search	Interface for querying groups based on attributes
whatsapp://groups/{groupId}/messages	Message history pertaining to a specific group

RESTful Gateway Endpoints

Contact & Dialogue Management

Endpoint	Method	Summary	Arguments
/api/status	GET	Query WhatsApp operational readiness	None
/api/contacts	GET	Fetch complete contact registry	None
/api/contacts/search	GET	Execute contact directory lookup	query: Search predicate
/api/chats	GET	Acquire listing of all dialogues	None
/api/messages/{number}	GET	Retrieve messages by contact ID	limit (query parameter): Record count
/api/send	POST	Transmit a singular message	number: Destination identifier message: Content payload

Group Administration

Endpoint	Method	Summary	Arguments
/api/groups	GET	Obtain list of all groups	None
/api/groups/search	GET	Perform group directory search	query: Search predicate
/api/groups/create	POST	Instantiate a new group container	name: Group designation participants: List of member IDs
/api/groups/{groupId}	GET	Retrieve detailed group specifications	None
/api/groups/{groupId}/messages	GET	Fetch group message history	limit (query parameter): Record count
/api/groups/{groupId}/participants/add	POST	Augment group membership	participants: List of new member IDs
/api/groups/send	POST	Distribute message to a group	groupId: Target group ID message: Content payload

AI Synergy

Integration with Desktop Agents (e.g., Claude)

Method A: Utilizing NPX Execution

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

2. Authenticate by scanning the displayed QR code using your WhatsApp mobile client.

3. Record the unique security token displayed in the service logs:

WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

1. Integrate the subsequent configuration block into your Claude Desktop preference file:

{ "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: Containerized Deployment (Docker)

1. Launch the WhatsApp Gateway service within a Docker container: 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 by scanning the QR code.

3. Capture the API security credential from the console:

WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

1. Incorporate this JSON structure into your Claude Desktop settings:

{ "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. Reinitialize the Claude Desktop application.
2. WhatsApp functionalities will subsequently be accessible through the Claude interface.

System Architecture

The codebase is structured to ensure a clear delineation of responsibilities:

Core Modules

1. WhatsAppService: Encompasses the fundamental operational logic for WhatsApp interaction.
2. WhatsAppApiClient: Handles the client-side connection protocols to the WhatsApp API layer.
3. API Router: The Express framework configuration defining the RESTful ingress points.
4. MCP Server: The dedicated implementation layer for the Model Context Protocol.

Deployment Configurations

1. WhatsApp Gateway Service: A self-contained RESTful server component.
2. MCP Server (Isolated): Establishes a direct session with the WhatsApp Web interface.
3. MCP Server (Gateway Client): Functions as a consumer, connecting to a pre-existing Gateway service.

This modular design promotes versatility across various deployment topologies, enabling: - Decoupling the Gateway service from the MCP processing unit across disparate hardware. - Utilizing the MCP server purely as a consumer layer interfacing with an established Gateway. - Consolidating all modules onto a single host for simplified setup.

Development Lifecycle

Directory Organization

src/ ├── whatsapp-client.ts # Implementation specific to the WhatsApp Web client interface ├── whatsapp-service.ts # Business logic core ├── whatsapp-api-client.ts # Client implementation for the WhatsApp API service ├── api.ts # REST API routing definitions ├── mcp-server.ts # MCP protocol implementation layer └── main.ts # Primary application bootstrap file

Source Compilation

bash npm run build

Quality Assurance (Testing)

Jest is utilized for unit validation routines. To execute the test suite:

bash

Execute all validation procedures

npm test

Enter development mode with continuous test execution monitoring

npm run test:watch

Generate a report detailing code coverage metrics

npm run test:coverage

Code Style and Consistency

ESLint and Prettier govern code hygiene and stylistic conformity:

bash

Execute static analysis checks

npm run lint

Automatically correct identifiable formatting errors

npm run lint:fix

Enforce Prettier formatting standards

npm run format

Comprehensive integrity check (Linting + Testing)

npm run validate

The linting rules are configured to enforce modern TypeScript conventions and maintain project-wide uniformity.

Diagnostic Assistance

Issues with Desktop Agent Integration

• Direct execution of the wweb-mcp in standalone command mode within environments like Claude is infeasible. This is due to Claude's multi-process initiation strategy, where each spawned wweb-mcp instance attempts to seize exclusive control over a Puppeteer session, causing authentication conflicts. The separation into distinct MCP and API modes was implemented specifically to circumvent this constraint and ensure smooth integration with agents like Claude.

Prospective Enhancements

• Implementation of event-driven webhooks for instantaneous notification of incoming messages and related WhatsApp lifecycle events.
• Support for payload transmission beyond plain text, including multimedia assets (images, audio, documentation).
• Expansion of group orchestration features.
• Functionality for contact provisioning and removal.
• Introduction of standardized message templates for recurring communication patterns.
• Hardening of error capture mechanisms and automated recovery protocols.

Collaboration Guidelines

1. Initiate work within a fork of this repository.
2. Create a dedicated feature branch for your modifications.
3. Commit your developmental progress.
4. Push the feature branch to your remote repository.
5. Submit a formal Pull Request (PR).

Ensure your submitted PR adheres to the following criteria: - Alignment with established coding style conventions. - Inclusion of relevant regression and unit tests. - Necessary updates to the associated documentation. - A thorough, clear explanation of the implemented changes.

Dependencies

Primary Dependency: WhatsApp Web.js

This utility relies heavily upon whatsapp-web.js, an unsanctioned JavaScript library facilitating connection to the WhatsApp Web browser interface. Further technical specifications are available at the whatsapp-web.js GitHub repository.

Licensing

This software is distributed under the terms of the MIT License; refer to the LICENSE file for comprehensive details.

Telemetry and Logging

WhatsApp Web MCP incorporates an advanced logging framework built upon Winston, offering:

• A spectrum of severity levels (error, warn, info, http, debug).
• Console output with syntax highlighting.
• Integrated logging for HTTP request/response traffic within the API layer.
• Structured mechanisms for handling exceptions.
• Log verbosity adjusted based on the execution environment (development vs. deployment).
• In command-line MCP transport mode, all diagnostic output is strictly routed to stderr.

Severity Tiers

The system recognizes the following log priorities, ordered from most critical to most verbose:

1. error - Catastrophic failures preventing core function.
2. warn - Non-fatal anomalies requiring eventual review.
3. info - General operational milestones and state updates.
4. http - Transactional logging for network communications.
5. debug - Granular, low-level diagnostic detail.

Log Filtering Configuration

The verbosity threshold can be configured upon initiation using the --log-level or -l command-line switch:

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

Or when invoking the globally installed utility:

bash wweb-mcp --log-level=debug

Command Mode Output Routing

When operating in MCP command mode (--mode mcp --transport command), all logged messages are directed exclusively to stderr. This separation is deliberate: stdout is reserved for the data stream conforming to the MCP specification, preventing log chatter from corrupting the protocol exchange.

Test Execution Context

When the runtime environment variable NODE_ENV is set to test (or during Jest execution), the logger automatically switches to a testing-optimized output profile.

WIKIPEDIA: Enterprise management solutions comprise the array of systems, software components, control mechanisms, analytical methods, and operational philosophies utilized by corporate entities to successfully navigate evolving market dynamics, secure competitive parity, and elevate overall organizational effectiveness. == System Classification == Business management instruments can be segmented based on departmental affiliation and functional aspect, such as those dedicated to foresight (planning), workflow optimization (process), record administration (records), human capital management, strategic determination (decision making), and performance oversight (control). A functional taxonomy typically identifies these general domains:

Instruments employed for the injection and validation of transactional data across all organizational units. Systems designed for the auditing and enhancement of core operational workflows. Platforms facilitating data aggregation and subsequent strategic inference. Modern management utilities have experienced exponential advancement in the last decade, driven by rapid technological maturation, making the selection of optimal business instruments for any given corporate scenario increasingly complex. This difficulty stems from the perpetual corporate mandate to minimize expenditure while maximizing revenue realization, coupled with the imperative to deeply comprehend consumer requirements and deliver products precisely matching those specifications. Within this dynamic landscape, executive leadership must adopt a strategic perspective on business management technology procurement rather than impulsively adopting novel solutions. Managers frequently implement tools without necessary tailoring, resulting in systemic instability. Consequently, organizational management instruments necessitate deliberate selection followed by meticulous modification to align with enterprise-specific requirements, rather than forcing the enterprise to conform to the tool's structure. == Predominant Instruments == A 2013 analysis by Bain & Company surveyed global utilization patterns of business instruments, reflecting regional needs shaped by market fluctuations and corporate performance levels. The ten most frequently cited instruments included:

Strategic roadmapping and goal setting Customer relationship lifecycle management Personnel satisfaction measurement through surveys Competitive analysis via benchmarking Performance monitoring via the Balanced Scorecard framework Identification and cultivation of core organizational competencies Strategic divestiture or management of external services (Outsourcing) Structured organizational transformation initiatives (Change management) Optimization of product flow networks (Supply chain) Formal documentation of organizational purpose (Mission/Vision statements) Detailed classification of target markets (Market segmentation) Comprehensive quality assurance methodologies (Total quality management) == Enterprise Software Applications == A computer program or suite of interconnected programs utilized by organizational personnel to execute diverse operational functions is defined as business software (or an enterprise application). These software solutions are employed to boost operational efficiency, quantitatively assess performance metrics, and execute various corporate tasks with high fidelity. The evolution spanned from early Management Information Systems (MIS) to comprehensive Enterprise Resource Planning (ERP) platforms, subsequently integrating Customer Relationship Management (CRM) capabilities, culminating in the current paradigm of cloud-centric business management ecosystems. Although a tangible linkage exists between Information Technology investments and corporate efficacy, value realization hinges critically on two factors: the proficiency of the implementation process and the judicious selection and customization of the requisite technological instruments. == Instruments for Small and Medium Enterprises (SMEs) == Tools tailored for SMEs are significant as they furnish avenues to achieve cost efficiencies and scale operations...