Ruandv/chatterbox_mcp_server
If you are the rightful owner of chatterbox_mcp_server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
Chatterbox MCP Server is a Model Context Protocol implementation designed for seamless integration with AI models and tools like WhatsApp.
🚀 Chatterbox MCP Server (indexed and certified by )
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 servermcp_server/src/model/tools.ts- MCP tools for WhatsApp operationsmcp_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 serverwhatsappServer/src/services/whatsappService.ts- WhatsApp Web.js integrationwhatsappServer/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
-
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 -
Install dependencies:
npm run install:all -
Start WhatsApp Server:
npm run dev:whatsapp -
Start MCP Server:
npm run dev:mcp -
Authenticate WhatsApp:
- Visit
http://localhost:3004/qrto get QR code - Scan with WhatsApp mobile app
- Visit
🛠️ 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 serverWHATSAPP_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 (trueorfalse)
Note: The CHATTERBOX_SECRET must be the same in both servers for authentication to work.
🐳 Docker
Each component has its own Dockerfile for containerization:
# WhatsApp Server
cd whatsappServer
docker build -t whatsapp-server .
# MCP Server
cd mcp_server
docker build -t mcp-server .
