MCP

WAHA MCP turns your self-hosted WAHA instance into a Model Context Protocol server.

Any MCP-compatible AI agent — Claude, Goose, OpenClaw, and others — can send messages, read chats, and manage contacts through your own infrastructure, with granular permission scopes so you decide exactly what the agent is allowed to do.

Requirements#

New in WAHA? Go over ⚡ Quick Start first.

Enable Apps in your WAHA configuration:

WAHA_APPS_ENABLED=True
WAHA_API_KEY=yoursecretkey

See 🧩 Apps for all available configuration options.

Setup#

Run WAHA with Apps enabled and your sessions folder mounted:

docker run -it \
  -e WAHA_APPS_ENABLED=True \
  -e WAHA_API_KEY=yoursecretkey \
  -v ./sessions:/app/.sessions \
  -p 3000:3000 \
  devlikeapro/waha-plus

Create an MCP App for the session you want to expose. WAHA automatically generates a scoped API key for that session — copy it from the app details to use in your MCP client.

Dashboard#

Open the 📊 Dashboard, navigate to your session’s Apps tab, and create a new MCP app. Set the permissions you want to grant the AI agent.

API#

POST /api/apps

{
  "enabled": true,
  "id": "app_mcp_default",
  "session": "default",
  "app": "mcp",
  "config": {
    "actions": {
      "read": true,
      "send": true,
      "control": false,
      "setting": false,
      "app": false,
      "delete": false
    }
  }
}

The response includes the generated API key in config.key — save it for your client configuration.

{
  "id": "app_mcp_default",
  "session": "default",
  "app": "mcp",
  "enabled": true,
  "config": {
    "key_id": "key_id_00000000000000000000000000",
    "key": "key_11111111111AAAAAAAAAAAAAAAAAAAAA",
    "actions": {
      "read": true,
      "send": true,
      "control": false,
      "setting": false,
      "app": false,
      "delete": false
    }
  }
}

Connect#

The MCP server is available at:

http://localhost:3000/mcp

Pass your API key as an HTTP header in your MCP client configuration:

X-Api-Key: YOUR_KEY

Claude Code#

claude mcp add --transport http whatsapp http://localhost:3000/mcp \
  --header "X-Api-Key: YOUR_KEY"

Claude Desktop#

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "whatsapp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:3000/mcp",
        "--header",
        "X-Api-Key:YOUR_KEY"
      ]
    }
  }
}

Goose#

Run goose configure in your terminal and walk through the prompts:

What would you like to configure?        → Add Extension
What type of extension?                  → Remote Extension (Streamable HTTP)
What would you like to call it?          → whatsapp
Streamable HTTP endpoint URI?            → http://localhost:3000/mcp
Timeout (in secs)?                       → 300
Enter a description                      → WhatsApp MCP
Add custom headers?                      → Yes
Header name:                             → X-Api-Key
Header value:                            → YOUR_KEY
Add another header?                      → No

In the desktop app the same flow lives under Settings → Extensions → Add custom extension. Goose stores extensions in ~/.config/goose/config.yaml so you can also edit that directly.

OpenClaw#

Add your server under mcp.servers in openclaw.json (typically ~/.openclaw/openclaw.json):

{
  "mcp": {
    "servers": {
      "whatsapp": {
        "url": "http://localhost:3000/mcp",
        "transport": "streamable-http",
        "connectionTimeoutMs": 10000,
        "headers": {
          "X-Api-Key": "YOUR_KEY"
        }
      }
    }
  }
}

Use transport: "streamable-http" (OpenClaw’s canonical spelling). You can also manage entries with openclaw mcp set / openclaw mcp list. If the server doesn’t appear, run openclaw gateway restart.

Permissions#

The actions field controls what the AI agent can do within the session. Set only the scopes you actually need — the key principle is least privilege.

A typical read + send only setup (good for a messaging assistant):

"actions": {
  "read": true,
  "send": true,
  "control": false,
  "setting": false,
  "app": false,
  "delete": false
}

Read more about scopes in 🔒 Session Key Scopes.

Examples#