🟢 OpenWA MCP Server

An enterprise-grade Model Context Protocol (MCP) server that seamlessly wraps the powerful OpenWA WhatsApp REST API. It exposes 44 robust tools over standard I/O (stdio) transport, enabling any MCP-compatible AI assistant (such as Cursor, Claude Desktop, Cline, and Antigravity) to securely manage WhatsApp sessions, dispatch multi-format messages, control group participants, search contacts, manage tag labels, and setup callbacks in real-time.

🧱 System Architecture

┌─────────────────────────────────────────────────────────────────┐
│             1. AI CLIENT (Cursor, Claude, Cline, etc.)          │
│  User: "Send a promotional flyer to my active VIP groups..."    │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼ [JSON-RPC over stdio]
┌─────────────────────────────────────────────────────────────────┐
│                 2. OPENWA MCP SERVER (TypeScript)               │
│  • Matches user request to the `send_image` tool schema         │
│  • Validates payload boundaries using declarative Zod schemas    │
│  • Authenticates securely via local dotenv environment configs   │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼ [REST API Request with X-API-Key]
┌─────────────────────────────────────────────────────────────────┐
│                 3. OPENWA WHATSAPP REST DAEMON                  │
│  • Translates API payloads into native WhatsApp Web calls       │
│  • Manages multi-session state machines & SQLite indexes        │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼ [WhatsApp Network Protocol]
┌─────────────────────────────────────────────────────────────────┐
│                     4. TARGET WHATSAPP DEVICES                  │
│  • Bulk promotional flyers delivered safely and instantly       │
└─────────────────────────────────────────────────────────────────┘

✨ Features

• 44 Built-in Tools: Comprehensive control over the entire WhatsApp ecosystem.

• Robust Zod Validation: Pure, declarative parameter validation on every request.

• Zero-Poll Webhooks: Simple callbacks to receive instant WhatsApp events directly.

• Multi-Session Native Engine: Manage multiple phone accounts under a single server wrapper.

• Strict Separation of Concerns: Highly modular, human-written TypeScript architecture.

🛠️ Installation & Setup

Prerequisites

• Node.js: v22.0.0 or higher

• TypeScript: v5.0.0 or higher

• A running and accessible OpenWA REST API instance

• A secure API Key generated from your OpenWA server configuration

1. Clone & Build

# Clone the repository
git clone https://github.com/ExoCubeYT/openwa-mcp.git
cd openwa-mcp

# Install dependencies
npm install

# Configure environment variables
cp .env.example .env

2. Configure Environment

Edit your local .env file to match your active OpenWA REST API backend:

OPENWA_BASE_URL=http://localhost:2785/api
OPENWA_API_KEY=your_secure_api_key_here

3. Build Production Targets

npm run build

The production output will compile cleanly into the dist/index.js bundle directory.

🚀 AI Agent Integrations

To load the OpenWA MCP server into your favorite developer environment, reference the standard JSON-RPC launch config.

Note: Replace C:/path/to/openwa-mcp with the absolute local filesystem path of your cloned workspace directory.

Claude Desktop

Edit your global configuration file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "openwa": {
      "command": "node",
      "args": ["C:/path/to/openwa-mcp/dist/index.js"],
      "env": {
        "OPENWA_BASE_URL": "http://localhost:2785/api",
        "OPENWA_API_KEY": "your_secure_api_key_here"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root (or set globally via Settings > Features > MCP):

{
  "mcpServers": {
    "openwa": {
      "command": "node",
      "args": ["C:/path/to/openwa-mcp/dist/index.js"],
      "env": {
        "OPENWA_BASE_URL": "http://localhost:2785/api",
        "OPENWA_API_KEY": "your_secure_api_key_here"
      }
    }
  }
}

Cline (VS Code Extension)

Edit your global extension state configurations in cline_mcp_settings.json:

{
  "mcpServers": {
    "openwa": {
      "command": "node",
      "args": ["C:/path/to/openwa-mcp/dist/index.js"],
      "env": {
        "OPENWA_BASE_URL": "http://localhost:2785/api",
        "OPENWA_API_KEY": "your_secure_api_key_here"
      },
      "disabled": false
    }
  }
}

Claude Code

Add .mcp.json to your project workspace root:

{
  "mcpServers": {
    "openwa": {
      "command": "node",
      "args": ["C:/path/to/openwa-mcp/dist/index.js"],
      "env": {
        "OPENWA_BASE_URL": "http://localhost:2785/api",
        "OPENWA_API_KEY": "your_secure_api_key_here"
      }
    }
  }
}

VS Code (Copilot / Continue / Open Code)

Create .vscode/mcp.json inside your local workspace:

{
  "servers": {
    "openwa": {
      "command": "node",
      "args": ["C:/path/to/openwa-mcp/dist/index.js"],
      "env": {
        "OPENWA_BASE_URL": "http://localhost:2785/api",
        "OPENWA_API_KEY": "your_secure_api_key_here"
      }
    }
  }
}

🧰 WhatsApp Tool Catalog (44 Total)

All tool schemas are structured logically using modular TypeScript domains under src/tools/.

📱 Sessions & Authentication (7)

💬 Messaging Services (8)

🚀 Bulk Campaigns (2)

👥 Group Orchestration (10)

📇 Contact Management (6)

🔔 Webhook Configs (4)

🏷️ Chat Labels (5)

📦 Media Assets (2)

🛠️ Local Development

To run the codebase in live-refresh watch mode during extensions, run:

# Spawns tsx to track active source code files directly
npm run dev

To run standard test transport handshakes, build the module and execute the diagnostic listener:

npm run build
node dist/index.js

🤝 Contributing

We welcome contributions of all shapes and sizes! To keep codebases pristine and secure, please adhere to our strict project design conventions.

Step-by-Step Contribution Flow

1. Fork the Repository: Set up your workspace branch on GitHub.

2. Implement Your Logic: Maintain strict separation of concerns. Keep your tools and clients isolated.

3. No AI Comments: Adhere to our zero AI-style commenting standard. Use short, human-like annotations where needed, and document details in .explanation files only.

4. Build & Test: Ensure npm run build generates zero TypeScript errors.

5. Create a Pull Request: Submit your pull request for review against our development branch.

See CONTRIBUTING.md for deeper details on our design paradigms.

📄 License

Distributed under the MIT License. See the LICENSE file for details.