Skip to main content
Glama
Ap0c123

WAHA MCP

by Ap0c123
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Local

WAHA MCP — WhatsApp via Docker MCP Toolkit

A self-hosted WhatsApp MCP server built on WAHA (WhatsApp HTTP API). Connects Claude Code, Claude Desktop, Cursor, Gemini, and other AI clients to WhatsApp through Docker's MCP Toolkit.

What's included

Component

Purpose

docker-compose.yml

Runs the WAHA container (WhatsApp HTTP API) on port 3000

mcp/server.js

Node.js MCP bridge — translates MCP tool calls into WAHA API requests

Dockerfile.mcp

Builds the MCP bridge as a Docker image for the Toolkit

toolkit-catalog.yaml

Registers the bridge in Docker MCP Toolkit

.mcp.json

Local MCP config for direct use (outside Docker Toolkit)

Prerequisites

  • Docker Desktop with MCP Toolkit enabled

  • Node.js 20+ (only needed if running the bridge locally outside Docker)

Installation

1. Clone and configure

git clone https://github.com/YOUR_USERNAME/waha-mcp.git
cd waha-mcp
cp .env.example .env

Edit .env and set your credentials:

WAHA_API_KEY=your-secret-api-key
WAHA_DASHBOARD_USERNAME=admin
WAHA_DASHBOARD_PASSWORD=your-dashboard-password
WHATSAPP_SWAGGER_USERNAME=admin
WHATSAPP_SWAGGER_PASSWORD=your-swagger-password

The WAHA_API_KEY can be any string — just keep it consistent between the WAHA container and the MCP bridge.

2. Start WAHA

docker compose up -d

WAHA will be available at http://localhost:3000. The dashboard is at http://localhost:3000/dashboard.

3. Build the MCP bridge image

docker build -f Dockerfile.mcp -t waha-whatsapp-mcp:latest .

4. Register with Docker MCP Toolkit

docker mcp catalog create waha-local
docker mcp catalog add waha-local whatsapp-waha-bridge ./toolkit-catalog.yaml --force
docker mcp catalog update waha-local
docker mcp server enable whatsapp-waha-bridge

5. Connect to your AI client

# Claude Code
docker mcp client connect claude-code

# Claude Desktop
docker mcp client connect claude-desktop

# Cursor
docker mcp client connect cursor

# Gemini
docker mcp client connect gemini

Restart your AI client after connecting.

6. Authenticate WhatsApp

On first run you need to scan a QR code to link WhatsApp:

  1. Ask your AI: "Start a WhatsApp session" — it will call waha_start_session

  2. Ask: "Show me the WhatsApp QR code" — it will call waha_get_qr

  3. In WhatsApp on your phone: Settings → Linked Devices → Link a Device → scan the QR

  4. Wait ~10 seconds and ask: "Is WhatsApp connected?" — status should be WORKING

Your session is saved in the .sessions/ volume and survives container restarts.

Available MCP tools

Session management

Tool

Description

waha_list_sessions

List all WAHA sessions

waha_get_session

Get session details and status

waha_start_session

Start a new session

waha_get_qr

Get QR code for authentication

waha_get_me

Get info about the authenticated account

Contacts & groups

Tool

Description

waha_lookup_contact_by_name

Find a contact by name

waha_list_chats

List recent chats

waha_search_groups

Search groups by name

waha_get_groups_in_common_with_user

Find groups shared with a contact

Messages

Tool

Description

waha_get_messages

Get messages from a chat

waha_get_last_inbound_message

Get the most recent incoming message

waha_get_last_message_from_contact

Get the last message from a specific contact

waha_search_messages

Search messages across chats

waha_history_status

Check message history sync status

waha_sync_recent_history

Sync recent message history

Sending

Tool

Description

waha_send_text

Send a text message by chat ID

waha_send_text_by_name

Send a text message by contact name

waha_send_text_to_group

Send a text message to a group by name

waha_send_image

Send an image

waha_send_file

Send a file

waha_send_video

Send a video

waha_send_voice

Send a voice message

Environment variables

Variable

Default

Description

WAHA_BASE_URL

http://127.0.0.1:3000

WAHA API base URL (bridge uses http://host.docker.internal:3000 when running inside Docker)

WAHA_API_KEY

(required)

Must match the key set in the WAHA container

WAHA_DASHBOARD_USERNAME

—

Dashboard login username

WAHA_DASHBOARD_PASSWORD

—

Dashboard login password

WHATSAPP_SWAGGER_USERNAME

—

Swagger UI login username

WHATSAPP_SWAGGER_PASSWORD

—

Swagger UI login password

Updating

To pick up changes to the MCP bridge:

git pull
docker build -f Dockerfile.mcp -t waha-whatsapp-mcp:latest .
docker mcp catalog add waha-local whatsapp-waha-bridge ./toolkit-catalog.yaml --force
docker mcp catalog update waha-local

Then restart your AI client.

Troubleshooting

Tools not appearing in your AI client

docker mcp server ls          # confirm whatsapp-waha-bridge is enabled
docker mcp client ls --global # confirm your client is connected

If the client shows disconnected: docker mcp client connect <client-name> then restart the client.

WhatsApp session dropped

docker compose up -d   # ensure WAHA is running

Then call waha_start_session and waha_get_qr to re-authenticate.

MCP bridge can't reach WAHA The toolkit container uses http://host.docker.internal:3000 to reach WAHA via the published port. Make sure the WAHA container is running and port 3000 is not blocked.

License

MIT

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Ap0c123/waha-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server