🚀 Chatterbox MCP Server
About
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…
Details
- Author
- Ruandv
- Downloads
- 146
- Categories
- Other
Jump to
- 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
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
🚀 Chatterbox MCP ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
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.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"\ud83d\ude80 chatterbox mcp server": {
"chatterbox_mcp_server": {
"command": "docker",
"args": [
"build",
"-t",
"whatsapp-server",
"."
]
}
}
}
}McpServers
{
"chatterbox_mcp_server": {
"command": "docker",
"args": [
"build",
"-t",
"whatsapp-server",
"."
]
}
}🚀 Chatterbox MCP Server (indexed and certified by MCPHub)
This repository contains two main components:
🤖 MCP Server (mcp_server/)
The Model Context Protocol server that provides WhatsApp functionality through MCP tools.
Key files:
- mcp_server/src/server.ts - Main MCP server
- mcp_server/src/model/tools.ts - MCP tools for WhatsApp operations
- mcp_server/src/model/resources.ts - MCP resources
Usage:
cd mcp_server
npm install
npm run dev
📱 WhatsApp Server (whatsappServer/)
The REST API server that handles actual WhatsApp Web integration.
Key files:
- whatsappServer/src/server.ts - Main Express server
- whatsappServer/src/services/whatsappService.ts - WhatsApp Web.js integration
- whatsappServer/src/controllers/whatsappController.ts - API endpoints
Usage:
cd whatsappServer
npm install
npm run dev
🔧 Architecture
┌─────────────────┐ HTTP API ┌─────────────────┐
│ │ Calls │ │
│ MCP Server │ ─────────────► │ WhatsApp Server │
│ │ │ │
└─────────────────┘ └─────────────────┘
│ │
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ MCP Client │ │ WhatsApp Web │
│ (Claude, etc) │ │ │
└─────────────────┘ └─────────────────┘
📁 Project Structure
chatterbox_mcp_server/
├── mcp_server/
│ ├── src/
│ ├── secrets/ # Secret files for MCP server
│ │ ├── CHATTERBOX_SECRET
│ │ └── WHATSAPP_SERVER_URL
│ └── package.json
├── whatsappServer/
│ ├── src/
│ ├── secrets/ # Secret files for WhatsApp server
│ │ ├── CHATTERBOX_SECRET
│ │ ├── PORT
│ │ └── HEADLESS
│ └── package.json
└── package.json
🚀 Quick Start
1. Set up secrets:
# MCP Server secrets (in mcp_server/secrets/)
echo "your_secret_here" > mcp_server/secrets/CHATTERBOX_SECRET
echo "http://localhost:3004" > mcp_server/secrets/WHATSAPP_SERVER_URL
# WhatsApp Server secrets (in whatsappServer/secrets/)
echo "your_secret_here" > whatsappServer/secrets/CHATTERBOX_SECRET
echo "3004" > whatsappServer/secrets/PORT
echo "true" > whatsappServer/secrets/HEADLESS
2. Install dependencies:
npm run install:all
3. Start WhatsApp Server:
npm run dev:whatsapp
4. Start MCP Server:
npm run dev:mcp
5. Authenticate WhatsApp:
- Visit http://localhost:3004/qr to get QR code
- Scan with WhatsApp mobile app
🛠️ Development
Each component can be developed independently:
- MCP Server focuses on MCP protocol implementation
- WhatsApp Server handles WhatsApp Web integration and API endpoints
📋 Required Secrets
Both servers use file-based secrets instead of environment variables for better security. Each secret is stored in a separate file within the secrets/ folder.
MCP Server (mcp_server/secrets/)
- CHATTERBOX_SECRET - Authentication secret for API calls to WhatsApp server
- WHATSAPP_SERVER_URL - URL of the WhatsApp server (e.g., http://localhost)
- SERVER_PORT - Port on which the server is listening on (e.g., 3004)
WhatsApp Server (whatsappServer/secrets/)
- CHATTERBOX_SECRET - Authentication secret (must match MCP server secret)
- PORT - Server port number (e.g., 3004)
- HEADLESS - Run WhatsApp in headless mode (true or false)
Note: The CHATTERBOX_SECRET must be the same in both servers for authentication to work.
🐳 Docker
Each component has its own Dockerfile for containerization:
```bash
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
