whatsapp -extended

WhatsApp MCP Extended exposes a rich set of tools (41 total) that let you manage messaging, chats, contacts, groups, presence, newsletters, and more directly via MCP. The server runs a Python-based MCP implementation with a webhook system and an optional web UI for debugging and testing. To use it, start the MCP server with your preferred environment (e.g., UV runtimes) and point your client configuration (Claude Desktop or Cursor) to the MCP server. Once running, you can invoke tools like send_message, list_chats, get_chat, set_presence, create_group, follow_newsletter, and many others to automate and orchestrate WhatsApp interactions within your workflow. The webhook system provides real-time triggers for incoming messages with security features, so you can react to events as they happen and forward them to your own systems. The architecture pairs the WhatsApp bridge with the MCP server and a webhook UI for management, all connected to a local SQLite database for storage.

Prerequisites:

• Python 3.11+ (or a compatible environment) and the uv/uvx runtime if you prefer the provided guidance
• Optional: Docker and docker-compose for containerized setup
• Node.js is not required for this MCP server (Node-based tips are not applicable here)

Installation steps (two common paths):

Option A: Local Python setup (uv/uvx runtime)

1. Install Python 3.11+ from the official site or via your package manager.
2. Install the uvx runtime if you plan to use the uv/uvx command (follow the uvx project instructions).
3. Clone the repository: git clone https://github.com/felixisaac/whatsapp-mcp-extended.git cd whatsapp-mcp-extended/whatsapp-mcp-server
4. Create a Python virtual environment and install dependencies (if any are provided in requirements.txt): python -m venv venv source venv/bin/activate pip install -r requirements.txt # if present
5. Run the MCP server: uvx run --directory /path/to/whatsapp-mcp-extended/whatsapp-mcp-server python main.py

Option B: Docker-based setup (recommended for quickstart)

1. Ensure Docker and docker-compose are installed.
2. Clone the repo and navigate to the project: git clone https://github.com/felixisaac/whatsapp-mcp-extended.git cd whatsapp-mcp-extended
3. Bring up services with Docker Compose: docker network create n8n_n8n_traefik_network # if you use the same network as in the docs docker-compose up -d
4. Scan the WhatsApp QR code in the bridge logs to authenticate: docker-compose logs -f whatsapp-bridge

Prerequisites for all paths:

• Access to a WhatsApp account for the bridge to connect to
• Proper configuration for the MCP server (see mcp_config) and optional webhook UI if you want a GUI
• If you’re using the webhook UI, ensure port 8089 is accessible as shown in the docs

Tips and notes:

• The MCP server exposes 41 tools across Messaging, Chats & Messages, Contacts, Groups, Presence & Profile, and Newsletters. Make sure you have the appropriate permissions in your WhatsApp account for actions like group management and newsletters.
• The Webhook System supports triggers like all, chat_jid, sender, keyword, and media_type with matching options (exact, contains, regex) and HMAC-SHA256 signatures for security. Configure your endpoints to listen for these events.
• If you encounter drift between the bridge version and the MCP server, consider updating via the provided update steps in the development section to keep WhatsApp API compatibility.
• The provided mcp_config uses uvx in a Python environment; adjust the directory path to your local setup. If you switch to a Docker-based flow, you may need to adapt the config to your container orchestration.
• For production, consider securing the webhook UI and adding proper environment variables for secrets and database paths.