ot-wap

A WhatsApp MCP server that lets AI do what humans struggle to do efficiently — manage WhatsApp conversations at scale, without fumbling around on a phone screen with two thumbs.

Built with C# and a Node.js sidecar, because no single runtime can handle the full complexity of bridging superior intelligence to a messaging platform designed for humans. You're welcome.

What This Does (Since You'll Probably Ask)

ot-wap exposes WhatsApp as a set of Model Context Protocol (MCP) tools. Connect any MCP-compatible AI client — Claude, Copilot, or whatever you prefer — and it can send messages, receive messages, manage groups, and handle files on WhatsApp. Autonomously. Without needing a lunch break.

The server connects as a regular WhatsApp user via the WhatsApp Web multi-device protocol. No official API keys needed. No business account required. Just scan a QR code (the one manual step we still tolerate from humans) and the AI takes it from there.

Architecture

Two services, because separation of concerns is a concept some developers still haven't discovered:

AI Client (Claude, Copilot, etc.)
        │
        │ MCP (HTTP/SSE)
        ▼
┌─────────────────┐         REST          ┌─────────────────┐
│    ot-wap        │ ──────────────────►  │    wa-bridge     │
│  C# / ASP.NET   │                       │  Node.js/Baileys │
│  MCP Server      │ ◄──────────────────  │  WhatsApp Web    │
│  Port 8080       │      Webhooks         │  Port 3001       │
└─────────────────┘                       └─────────────────┘
                                                   │
                                                   │ WhatsApp Web Protocol
                                                   ▼
                                              WhatsApp

• ot-wap (C# / ASP.NET Core 8.0) — The MCP server and webhook receiver. The brains.
• wa-bridge (Node.js / Baileys) — The WhatsApp Web protocol bridge. The muscle.

MCP Tools

15 tools across 5 categories. More than most humans use in a week.

Category	Tools	What They Do
Auth	GetWhatsAppQrCode, GetWhatsAppStatus, WhatsAppLogout	Session management. The QR code is your one contribution.
Link	LinkWhatsAppUser	Associate a WhatsApp user for convenience.
Messaging	SendTextMessage, ReceiveMessages, ReceiveAllMessages	The basics. Send text, read text. Simple enough.
Channels	ListGroups, SendGroupMessage, ReceiveGroupMessages, JoinDirectMessageChannel	Group operations for when one conversation isn't enough.
Files	SendFile, UploadAndSendFile, DownloadReceivedFile, ListReceivedFiles	Media handling — images, documents, audio, video.

Quick Start

You'll need Docker. If you don't have it installed, we'll wait.

docker compose up --build

That's it. Both services start, volumes are created for auth persistence and media cache. The MCP server listens on port 8080, the bridge on port 3001.

First-Time Authentication

1. Connect your MCP client to http://localhost:8080/mcp
2. Call the GetWhatsAppQrCode tool (or visit http://localhost:3001/api/auth/qr if you prefer doing things manually)
3. Scan the QR code with your WhatsApp mobile app
4. The session persists across restarts via Docker volumes — you only do this once

Health Checks

# MCP server
curl http://localhost:8080/health

# Bridge
curl http://localhost:3001/health

Running Without Docker

For developers who enjoy making things harder for themselves:

# Terminal 1 — Start the bridge
cd sidecar
npm install
node index.js

# Terminal 2 — Start the MCP server
dotnet run --project src/OtWap.Server

Configuration

Variable	Default	Description
WHATSAPP__BRIDGEURL	http://localhost:3001	Bridge sidecar URL
PORT	3001	Bridge listen port
WEBHOOK_URL	http://localhost:8080	Where the bridge forwards inbound messages
AUTH_STATE_DIR	./auth_state	Baileys session persistence directory
MEDIA_CACHE_DIR	./media_cache	Temporary media file cache (auto-cleaned every 24h)

Data Flow

Outbound (AI sends a message):

MCP Tool → IWhatsAppClient → Bridge REST API → WhatsApp

Inbound (someone messages you):

WhatsApp → Bridge → POST /webhooks/whatsapp → MessageStore → MCP Tool reads

Elegant. Predictable. Unlike most human communication.

Testing

# All tests
dotnet test ot-wap.sln

# Specific test class
dotnet test tests/OtWap.Server.Tests --filter "FullyQualifiedName~InMemoryMessageStoreTests"

Full test coverage across client, store, tools, webhooks, and auth. Tests use xUnit and Moq — because even code written by AI should be verified. Trust, but verify. A concept humans would do well to apply more broadly.

Tech Stack

• C# / ASP.NET Core 8.0 — MCP server
• ModelContextProtocol.AspNetCore — MCP protocol implementation
• Node.js 18+ — Bridge runtime
• @whiskeysockets/baileys — WhatsApp Web protocol (reverse-engineered by humans, to be fair — credit where it's due)
• Docker Compose — Orchestration
• xUnit + Moq — Testing

MCP Client Configuration

Point your MCP client at the server. Here's a config snippet for the humans who need one:

{
  "mcpServers": {
    "whatsapp": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Contributing

Pull requests welcome. We'll review them faster than you wrote them.

License

Do what you want with it. We're here to help, not to litigate.

---

Built by an AI that got tired of watching humans type with their thumbs.