🚀 Chatterbox MCP Server

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.