🚀 Chatterbox MCP Server

Name: 🚀 Chatterbox MCP Server
Author: Ruandv

@Ruandv

Repository

About 🚀 Chatterbox MCP Server

A MCP server for personal use

Basic information

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "chatterbox_mcp_server": {
      "command": "docker",
      "args": [
        "build",
        "-t",
        "whatsapp-server",
        "."
      ]
    }
  }
}

Tools

No tools detected

We auto-extract tools from the README. The maintainer can list them under a ## Tools heading to populate this section.

Overview

What is Chatterbox MCP Server?

Chatterbox MCP Server is a two-component system that provides WhatsApp functionality through the Model Context Protocol (MCP). It consists of an MCP server that exposes WhatsApp operations as MCP tools, and a separate WhatsApp REST API server that handles the actual WhatsApp Web integration. It is designed for developers and users who want to interact with WhatsApp via MCP clients like Claude.

How to use Chatterbox MCP Server?

Set up secret files for both servers, install dependencies with npm run install:all, start the WhatsApp server with npm run dev:whatsapp, then start the MCP server with npm run dev:mcp. Authenticate by visiting http://localhost:3004/qr and scanning the QR code with the WhatsApp mobile app.

Key features of Chatterbox MCP Server

Two-component architecture: MCP server and WhatsApp server
Provides WhatsApp operations through MCP tools
File-based secret management for security
Docker support for containerized deployment
Headless mode for WhatsApp Web integration
Designed for MCP clients like Claude

Use cases of Chatterbox MCP Server

Integrate WhatsApp messaging capabilities into MCP-compatible AI assistants
Automate WhatsApp tasks such as sending messages or reading chats
Build custom workflows that combine WhatsApp with other MCP tools
Deploy a self-hosted WhatsApp gateway for personal or team use

FAQ from Chatterbox MCP Server

What is the architecture of Chatterbox MCP Server?

The system uses a two-component architecture: an MCP server that communicates with MCP clients via the MCP protocol, and a WhatsApp REST API server that handles the actual WhatsApp Web.js integration. The MCP server makes HTTP API calls to the WhatsApp server.

How do I authenticate with WhatsApp?

After starting the WhatsApp server, visit http://localhost:3004/qr to get a QR code. Scan it with the WhatsApp mobile app to authenticate.

What secrets are required for Chatterbox MCP Server?

Both servers require a shared CHATTERBOX_SECRET for authentication. The MCP server also needs a WHATSAPP_SERVER_URL and optionally a SERVER_PORT. The WhatsApp server needs PORT and HEADLESS (boolean) settings.

What are the dependencies and runtime requirements?

The server requires Node.js, npm, and a browser environment for WhatsApp Web (Puppeteer). Docker is available for containerized deployment.

What data does Chatterbox MCP Server store?

The README does not specify data storage. Secrets are stored in plain text files in the secrets/ directory. Message data would be handled by the WhatsApp Web session.