trackmcp
Back to directory
Ronnie-Leon76

whatsapp-flows-mcp-server

View on GitHub

WhatsApp Flows MCP Server for business to automate survey creation and data collection through WhatsApp platform

0 stars TypeScriptServers & Infrastructure Updated Jun 4, 2025

Documentation

🚀 WhatsApp Flows API MCP Server


✨ Features

  • 🐳 Dockerized Architecture - Complete containerized setup with Redis and background processing
  • 🔧 Modular ERP Integration - Support for Business Central, SAP, Oracle, and custom ERP systems
  • Background Processing - Async job processing for handling large customer lists
  • 📱 WhatsApp Flow Management - Create and send interactive surveys via WhatsApp Business API
  • 📊 Monitoring Tools - Built-in dashboards for job monitoring and Redis management
  • 🔄 Development Support - Hot reload and development containers for rapid iteration

🚀 Quick Start

Prerequisites

Before you begin, ensure you have:

  • ✅ Docker and Docker Compose installed
  • ✅ WhatsApp Business API credentials
  • ✅ Environment variables configured

1️⃣ Clone and Configure

bash
git clone https://github.com/Ronnie-Leon76/whatsapp-flows-mcp-server.git
cd whatsapp-flows-mcp-server

# Copy and configure environment variables
cp .env.example .env
# Edit .env with your WhatsApp Business API credentials

2️⃣ Start Services

🏭 Production Mode

bash
make start
# or
./scripts/start.sh

🛠️ Development Mode (with hot reload)

bash
make start-dev
# or
./scripts/start-dev.sh

3️⃣ Access Services

ServiceURLDescription
MCP ServerRunning in containerMain MCP server (stdio transport)
Job Dashboardhttp://localhost:3001Monitor background jobs
Redis Commanderhttp://localhost:8081Redis management interface
Redislocalhost:6379Redis instance

🏗️ Architecture

Docker Services Overview

mermaid
graph TB
    A[MCP Server] --> D[Redis Job Queue]
    B[Job Worker 1] --> D
    C[Job Worker 2] --> D
    D --> E[Job Dashboard]
    D --> F[Redis Commander]
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#f3e5f5
    style D fill:#ffebee
    style E fill:#e8f5e8
    style F fill:#fff3e0

Core Services

ServicePurposeReplicas
mcp-serverMain MCP server1
redisJob queue and caching1
job-workerBackground job processing2
job-dashboardJob monitoring web UI1
redis-commanderRedis management UI1

🛠️ Commands Reference

Make Commands

CommandDescription
`make help`📋 Show all available commands
`make build`🔨 Build Docker images
`make start`▶️ Start production services
`make start-dev`🛠️ Start development services
`make stop`⏹️ Stop all services
`make logs`📜 View logs from all services
`make logs-mcp`📜 View MCP server logs
`make logs-celery`📜 View worker logs
`make clean`🧹 Clean up Docker resources
`make restart`🔄 Restart all services
`make shell-mcp`🐚 Open shell in MCP container
`make shell-celery`🐚 Open shell in worker container
`make redis-cli`💾 Open Redis CLI

NPM Scripts

bash
npm run docker:build      # Build Docker images
npm run docker:start      # Start production services
npm run docker:start-dev  # Start development services
npm run docker:stop       # Stop all services
npm run docker:logs       # View logs

⚙️ Configuration

🔑 Required Environment Variables

env
# WhatsApp Business API Configuration
WHATSAPP_ACCESS_TOKEN=your_access_token_here
WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id_here
WHATSAPP_BUSINESS_ACCOUNT_ID=your_business_account_id_here
WHATSAPP_VERIFY_TOKEN=your_verify_token_here

🔧 Optional Environment Variables

env
# Redis Configuration (auto-configured in Docker)
REDIS_URL=redis://redis:6379/0

# Worker Configuration
WORKER_CONCURRENCY=5

# Dashboard Configuration
PORT=3001

# Paths (auto-configured in Docker)
CONFIG_PATH=/app/config
SURVEYS_PATH=/app/surveys

🛠️ Development

Hot Reload Development

bash
# Start development environment with hot reload
make start-dev

# View development logs
docker-compose -f docker-compose.dev.yml logs -f

Local Development (without Docker)

bash
# Start Redis locally
docker run -d -p 6379:6379 redis:7-alpine

# Install dependencies
npm install

# Start MCP server
npm run dev

# Start worker (in separate terminal)
cd celery_app
celery -A tasks worker --loglevel=info

📊 Monitoring & Debugging

📈 Job Dashboard

Access at http://localhost:3001 to:

  • ✅ Monitor active/completed jobs
  • 📋 View job details and progress
  • 👥 Monitor worker status
  • ⚡ Real-time job execution tracking

💾 Redis Commander

Access at http://localhost:8081 to:

  • 🔍 Browse Redis keys
  • 📊 Monitor Redis performance
  • 👁️ View stored data
  • 🔧 Debug Redis issues

🔧 New MCP Tools

  • `send-survey` - Background job processing for large customer lists
  • `get-job-status` - Monitor background job progress
  • `get-queue-stats` - View job queue statistics

📜 Viewing Logs

bash
# All services
make logs

# Specific service
docker-compose logs -f mcp-server
docker-compose logs -f job-worker
docker-compose logs -f redis

# Follow logs in real-time
docker-compose logs -f --tail=100

🚀 Production Deployment

Docker Compose Production

bash
# Start production services
make start

# Scale workers
docker-compose up -d --scale job-worker=4

# Update services
docker-compose pull
docker-compose up -d

🏥 Health Checks

All services include comprehensive health checks:

ServiceHealth Check
Redis`redis-cli ping`
MCP ServerNode.js health endpoint
Job WorkerWorker status ping

💾 Persistent Data

Data persistence through Docker volumes:

VolumePurpose
`redis_data`Redis database
`mcp_config`ERP configurations
`mcp_surveys`Survey definitions
`mcp_logs`Application logs
`worker_logs`Worker logs

🔧 Troubleshooting

Common Issues

🚫 Services won't start

bash
# Check Docker status
docker-compose ps

# View service logs
make logs

# Check system resources
docker stats

🔴 Redis connection issues

bash
# Test Redis connection
make redis-cli
ping

# Check Redis logs
docker-compose logs redis

⚠️ Jobs not processing

bash
# Check worker status
make logs-celery

# Access job dashboard
open http://localhost:3001

# Check Redis queue
make redis-cli
LLEN job_queue

🔑 Environment variables not loaded

bash
# Verify .env file exists and is configured
cat .env

# Restart services
make restart

# Check environment in container
docker-compose exec mcp-server env | grep WHATSAPP

🔍 Debugging

bash
# Access container shells
make shell-mcp      # MCP server container
make shell-celery   # Worker container

# View container resources
docker stats

# Inspect container configuration
docker-compose config

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.


Frequently asked questions

What is whatsapp-flows-mcp-server?

whatsapp-flows-mcp-server is WhatsApp Flows MCP Server for business to automate survey creation and data collection through WhatsApp platform

How do I install whatsapp-flows-mcp-server?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is whatsapp-flows-mcp-server open source?

Yes — it is hosted on GitHub at https://github.com/Ronnie-Leon76/whatsapp-flows-mcp-server.

Related MCP tools

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP