WhatsApp Web

You can run a MCP server that bridges WhatsApp Web with AI models, enabling automated messaging, contact management, and group interactions through a standardized Model Context Protocol interface. This guide walks you through using the server with MCP clients, installing it, and configuring common options for development and testing.

How to use

Launch the MCP server to either connect directly to WhatsApp Web or to a dedicated WhatsApp API server. You will typically run one of the following modes, then use an MCP client to issue actions such as sending messages, managing chats and groups, or retrieving history.

How to install

Prerequisites: you need Node.js installed on your system. You may also use Docker for containerized deployment.

# Install Node.js from https://nodejs.org/
# Then clone the project and install dependencies
git clone https://example.org/placeholder/wweb-mcp.git
cd wweb-mcp
npm install

Additional setup and configuration

Configure how you connect to WhatsApp and how the MCP server exposes its interfaces. You can run the MCP server in standalone mode with SSE transport on a specific port, or you can run in API client mode to connect to a separate WhatsApp API server.

Common options you will use include enabling the MCP server in standalone or API-connected modes, selecting the transport (SSE or command), and setting ports. If you plan to connect to a separate WhatsApp API server, you will provide the API base URL and an API key.

npx wweb-mcp --mode mcp --mcp-mode standalone --transport sse --sse-port 3002

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

Running the API server for integration

If you want an isolated REST API surface for WhatsApp functionality, you can start a standalone API server and then run an MCP server that uses that API.

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

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

Security and testing notes

This tool is intended for testing scenarios and should not be used in production environments. Some integrations may be more stable with local authentication where credentials persist between sessions.

Troubleshooting

If you encounter integration issues with Claude or other tools, ensure you are starting the MCP server in a mode compatible with the client’s expectations and that the API key and base URL (when using an API mode) are correctly configured.

Available tools

get_status

Check WhatsApp client connection status

send_message

Send messages to WhatsApp contacts

search_contacts

Search for contacts by name or number

get_messages

Retrieve messages from a specific chat

get_chats

Get a list of all WhatsApp chats

create_group

Create a new WhatsApp group

add_participants_to_group

Add participants to an existing group

get_group_messages

Retrieve messages from a group

send_group_message

Send a message to a group

search_groups

Search for groups by name, description, or member names

get_group_by_id

Get detailed information about a specific group

download_media_from_message

Download media from a message

send_media_message

Send a media message to a WhatsApp contact