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 40 tools across sessions, messages, contacts, groups, and webhooks — so an agent (MaxKB, Claude, Cursor, any MCP client) can read and send WhatsApp messages through your self-hosted OpenWA gateway.

Features

• 40 curated tools mapped 1:1 from the OpenWA REST API spec
• 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)

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

Env var	Default	Description
OPENWA_URL	http://localhost:2785	Base URL of your OpenWA instance
OPENWA_API_KEY	—	OpenWA API key (required)
MCP_TOKEN	(empty)	Bearer token MCP clients must send. If set, requests without Authorization: Bearer <token> get 401. Leave empty to disable auth (localhost only).
PORT	3000	Port the MCP server listens on

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 (40)

Sessions — list_sessions · session_status · session_qr · session_start · session_stop

Send — send_text · send_image · send_video · send_document · send_audio · send_sticker · 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 · block_contact · unblock_contact

Groups — list_groups · get_group · create_group · group_add_participants · group_remove_participants · group_set_subject · group_set_description · group_join · group_get_invite

Webhooks — list_webhooks · create_webhook · delete_webhook

Project Structure

openwa-mcp/
├── src/
│   ├── index.ts      # Hono app + StreamableHTTP transport at /mcp
│   └── mcp.ts        # MCP server definition + 40 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.
• 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