OpenWA MCP Server

Model Context Protocol (MCP) server that bridges AI agents to the OpenWA WhatsApp API. Built with Bun + Hono and the official @hono/mcp transport.

Exposes 22 tools covering messaging, chat/contact reads, and read-only session status — so an agent (MaxKB, Claude, Cursor, any MCP client) can read and send WhatsApp messages through your self-hosted OpenWA gateway. Session start/stop, webhook admin, group admin, and block/unblock are implemented in the OpenWA REST API but intentionally not registered as MCP tools (see Tool allowlist below).

Features

• 22 curated tools, allowlisted from the full OpenWA REST API spec — no infra/admin surface exposed to the agent

• Streamable HTTP transport at /mcp (single port, no extra process)

• Zod-validated inputs on every tool

• Optional bearer-token auth on the MCP endpoint (MCP_TOKEN)

• Zero config — one env var (API key), works with the default OpenWA setup

• Docker-ready multi-stage build (oven/bun)

Related MCP server: wa-bridge

Requirements

• Node 22+ (or just use the included Dockerfile)

• A running OpenWA instance

• An OpenWA API key (owa_k1_...) — create one in the dashboard under API Keys (OPERATOR role for send tools)

Quick Start

cp .env.example .env        # set OPENWA_URL + OPENWA_API_KEY
bun install
bun run dev                 # → http://localhost:3000/mcp

Docker

cp .env.example .env
docker compose up -d --build

Configuration

Connecting a client

Point any MCP client at the Streamable HTTP endpoint. If MCP_TOKEN is set, include it in headers:

{
  "mcpServers": {
    "openwa": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_TOKEN>"
      }
    }
  }
}

Verify the handshake (include the token if MCP_TOKEN is set):

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <MCP_TOKEN>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Tools (22)

Sessions (read-only) — list_sessions · session_status

Send — send_text · send_menu · send_image · send_video · send_document · send_audio · send_location · send_contact · send_poll

Message actions — reply_message · forward_message · react_message · edit_message · delete_message

Read — chat_history (live from WhatsApp) · list_messages (from local DB) · list_chats

Contacts — contact_check · list_contacts · get_contact

Tool allowlist

The full OpenWA REST API surface is implemented in src/mcp.ts's openwa() client, but only the tools listed above are registered on the MCP server — everything else (session_qr, session_start, session_stop, send_sticker, block_contact, unblock_contact, all group_* tools, and all webhook_* tools) is intentionally left unregistered, not just hidden. See the ENABLED_TOOLS allowlist and tool() wrapper near the top of src/mcp.ts.

Rationale: this server is meant to back a chat agent (see the Vivita-style system prompt pattern) that reads/sends messages and looks up chats/contacts — it has no legitimate reason to start/stop WhatsApp sessions, manage webhooks, or administer groups. Keeping those out of the registered tool set means a leaked MCP_TOKEN or a prompt-injected tool call can't touch infra state, even though the underlying OpenWA API key could technically do more. To re-enable a tool, add its name to ENABLED_TOOLS in src/mcp.ts.

Project Structure

openwa-mcp/
├── src/
│   ├── index.ts      # Hono app + StreamableHTTP transport at /mcp
│   └── mcp.ts        # MCP server definition + tool allowlist + tools (Zod schemas)
├── Dockerfile        # multi-stage oven/bun build
├── docker-compose.yml
├── package.json
├── .env.example
└── README.md

Notes

• Two auth layers: the optional MCP_TOKEN gates the MCP endpoint itself (clients send Authorization: Bearer <token>); the OPENWA_API_KEY is held server-side and forwarded as the X-API-Key header to OpenWA on every call. Clients never see the OpenWA key.

• Send tools return 201 = accepted by the gateway, not delivered. Check contacts/check first for new numbers.

• chat_history requires the Baileys engine on OpenWA (whatsapp-web.js does not support it — returns 501).

• Media sends accept either url or base64 (+ mimetype); decoded size capped at 50 MiB by OpenWA.

• No quick-reply buttons — unofficial engines (whatsapp-web.js/Baileys) can't render interactive buttons; that's an official-Cloud-API-only feature. Use send_menu (numbered text menu) instead.

• If you expose the server publicly: set MCP_TOKEN, and use a dedicated session-scoped OpenWA key (OPERATOR at most) rather than a master key.

License

MIT