🚀 Chatterbox MCP Server

🚀 Chatterbox MCP Server（已由 MCPHub 收录并认证）

此仓库包含两个主要组件：

🤖 MCP 服务（mcp_server/）

通过 MCP 工具提供 WhatsApp 功能的模型上下文协议服务。

主要文件：

• mcp_server/src/server.ts - 主 MCP 服务
• mcp_server/src/model/tools.ts - 用于 WhatsApp 操作的 MCP 工具
• mcp_server/src/model/resources.ts - MCP 资源

用法：

cd mcp_server
npm install
npm run dev

📱 WhatsApp 服务（whatsappServer/）

处理实际 WhatsApp Web 集成的 REST API 服务。

主要文件：

• whatsappServer/src/server.ts - 主 Express 服务
• whatsappServer/src/services/whatsappService.ts - WhatsApp Web.js 集成
• whatsappServer/src/controllers/whatsappController.ts - API 端点

用法：

cd whatsappServer
npm install
npm run dev

🔧 架构

┌─────────────────┐    HTTP API    ┌─────────────────┐
│                 │    Calls       │                 │
│   MCP Server    │ ─────────────► │ WhatsApp Server │
│                 │                │                 │
└─────────────────┘                └─────────────────┘
        │                                   │
        │                                   │
        ▼                                   ▼
┌─────────────────┐                ┌─────────────────┐
│  MCP Client     │                │  WhatsApp Web   │
│  (Claude, etc)  │                │                 │
└─────────────────┘                └─────────────────┘

📁 项目结构

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

🚀 快速开始

1. 设置密钥：

   # 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. 安装依赖：

   npm run install:all
   

3. 启动 WhatsApp 服务：

   npm run dev:whatsapp
   

4. 启动 MCP 服务：

   npm run dev:mcp
   

5. 验证 WhatsApp 身份：

   • 访问 http://localhost:3004/qr 获取二维码
   • 使用 WhatsApp 移动应用扫描

🛠️ 开发

每个组件都可以独立开发：

• MCP 服务专注于 MCP 协议实现
• WhatsApp 服务负责 WhatsApp Web 集成和 API 端点

📋 所需密钥

为了提高安全性，两个服务都使用基于文件的密钥，而不是环境变量。每个密钥都存储在 secrets/ 文件夹中的单独文件里。

MCP 服务（mcp_server/secrets/）

• CHATTERBOX_SECRET - 用于向 WhatsApp 服务发起 API 调用的身份验证密钥
• WHATSAPP_SERVER_URL - WhatsApp 服务的 URL（例如，http://localhost）
• SERVER_PORT - 服务监听的端口（例如，3004）

WhatsApp 服务（whatsappServer/secrets/）

• CHATTERBOX_SECRET - 身份验证密钥（必须与 MCP 服务的密钥一致）
• PORT - 服务端口号（例如，3004）
• HEADLESS - 以无头模式运行 WhatsApp（true 或 false）

注意： 两个服务中的 CHATTERBOX_SECRET 必须相同，身份验证才能正常工作。

🐳 Docker

每个组件都有自己的 Dockerfile，用于容器化：

# WhatsApp Server
cd whatsappServer
docker build -t whatsapp-server .

# MCP Server
cd mcp_server
docker build -t mcp-server .