Skip to main content
Glama
waha-fast-mcp
by CatalaniCD

waha-fast-mcp

A fast, single-module MCP server that exposes a local WAHA (WhatsApp HTTP API) instance as tools for MCP hosts and LangChain agents.

It is a conservative simplification of waha-langchain-mcp: the HTTP client and the tool layer live in one server.py, the 18 tool contracts are unchanged, and the operational guide is shipped as SKILL.md and exposed through the waha_skill MCP prompt.

flowchart LR
    subgraph Host["MCP host or LangChain process"]
        A["Agent"]
        C["MCP client"]
        A --> C
    end
    subgraph Server["waha-fast-mcp (single module, stdio by default)"]
        P["prompt: waha_skill"]
        T["18 MCP tools"]
        W["WahaClient"]
        P -.->|"reads"| S["SKILL.md"]
        T --> W
    end
    C -->|"JSON-RPC"| T
    W -->|"HTTP + X-Api-Key"| WAHA["WAHA :3000"]
    WAHA <--> WhatsApp

Tools

Area

Tools

Sessions

waha_status, waha_list_sessions, waha_get_session, waha_get_me, waha_start_session, waha_stop_session, waha_create_session

Chats and messages

waha_list_chats, waha_get_chat, waha_get_chat_messages, waha_mark_chat_read, waha_set_typing, waha_take_screenshot

Sending

waha_send_text, waha_send_image, waha_send_file

Contacts

waha_check_number_exists, waha_get_profile_picture

Prompt: waha_skill returns SKILL.md, which documents the lifecycle, chat ID formats, send guardrails, media rules, and error handling.

Inbound messages are not pushed over MCP. Point a WAHA webhook at your application for inbound automation.

Related MCP server: MCP WhatsApp

Setup

cd /home/user/Projects/aegra-content/waha-fast-mcp
uv sync --extra dev --extra examples
cp .env.example .env

Set WAHA_API_KEY in .env. The server reads WAHA_BASE_URL, WAHA_API_KEY, and WAHA_TIMEOUT.

Verify the server and the live WAHA connection:

uv run python -m waha_fast_mcp --pretty
uv run pytest

--pretty prints the tool catalog as JSON and exits without starting a server. pytest runs without WAHA; live tests are opt-in with WAHA_LIVE=1.

Use with an MCP host

{
  "mcpServers": {
    "waha": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/home/user/Projects/aegra-content/waha-fast-mcp",
        "waha-fast-mcp"
      ],
      "env": {
        "WAHA_BASE_URL": "http://localhost:3000",
        "WAHA_API_KEY": "<your-key>"
      }
    }
  }
}

The server defaults to stdio. Optional SSE or streamable HTTP:

WAHA_MCP_TRANSPORT=streamable-http uv run waha-fast-mcp

Use with LangChain

The examples spawn python -m waha_fast_mcp over stdio and pass the API key in the child process environment, never to the model.

uv run python examples/list_tools.py
uv run python examples/react_agent.py "Show my 5 most recent chats"
uv run python examples/deep_agent.py "Summarize my unread chats"

Minimal wiring:

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({
    "waha": {
        "command": "python",
        "args": ["-m", "waha_fast_mcp"],
        "transport": "stdio",
        "env": {"WAHA_BASE_URL": "http://localhost:3000", "WAHA_API_KEY": "..."},
    }
})
tools = await client.get_tools()

Security

  • Keep WAHA_API_KEY in the environment or .env; it is never a tool argument.

  • Sending messages and starting/stopping sessions are real side effects. Require explicit user intent and a human gate where the host supports one.

  • waha_send_image / waha_send_file accept local paths, so the stdio server can read files with the agent process's permissions.

  • SKILL.md is advisory. Hard requirements, such as blocking sends to protected chats, must be enforced by a host permission rule or hook.

  • The default transport is stdio. If you expose HTTP, bind to localhost and add authentication.

Documentation

License

MIT. See LICENSE.

Available Tools

18 tools
waha_check_number_existsB

Check whether a phone number (digits only, with country code) has WhatsApp.

Inputs: phone (required), session (required). Returns: object

waha_create_sessionC

Create a new WhatsApp session. Scan its QR code with the dashboard.

Inputs: name (required), start. Returns: object

waha_get_chatB

Get details about a chat. chat_id is like '549...@c.us' or '...@g.us'.

Inputs: chat_id (required), session (required). Returns: object

waha_get_chat_messagesB

Read messages from a chat, newest first. Use the id from waha_list_chats.

Inputs: chat_id (required), session (required), limit, offset, +1 more. Returns: object

waha_get_meB

Return the WhatsApp account (id, lid, pushName) linked to a session.

Inputs: session (required). Returns: object

waha_get_profile_pictureC

Get the profile picture URL for a contact or group.

Inputs: session (required), contact_id (required). Returns: object

waha_get_sessionB

Get one session, including its status and the linked WhatsApp account.

Inputs: session (required). Returns: object

waha_list_chatsC

List recent chats for a session, newest first.

Inputs: session (required), limit, offset. Returns: object

waha_list_sessionsC

List WhatsApp sessions. Set include_stopped to True to include stopped ones.

Inputs: include_stopped. Returns: object

waha_mark_chat_readC

Mark all messages in a chat as read.

Inputs: chat_id (required), session (required). Returns: result

waha_send_fileC

Send a document from a URL, local path, or base64 data, with optional caption.

Inputs: chat_id (required), session (required), url, path, +4 more. Returns: object

waha_send_imageC

Send an image from a URL, local path, or base64 data, with optional caption.

Inputs: chat_id (required), session (required), url, path, +4 more. Returns: object

waha_send_textC

Send a text WhatsApp message. Optionally pass reply_to as a message id.

Inputs: text (required), chat_id (required), session (required), reply_to. Returns: object

waha_set_typingC

Show or hide the 'typing...' indicator in a chat.

Inputs: chat_id (required), session (required), typing. Returns: result

waha_start_sessionB

Start a stopped WhatsApp session. Scan its QR code with the dashboard.

Inputs: session (required). Returns: object

waha_statusA

Check WAHA connectivity and return server status and version.

Inputs: no named parameters. Returns: object

waha_stop_sessionB

Stop a running WhatsApp session without deleting its data.

Inputs: session (required). Returns: object

waha_take_screenshotA

Capture the current WhatsApp Web screen and return the saved file path.

Inputs: session (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 18 tools

    Disambiguation4/5

    Most tools target a distinct resource+action (sessions, chats, messages, media). The only mild overlaps are waha_get_session vs waha_get_me (the former already reports the linked account) and waha_send_image vs waha_send_file, which differ only by media type and are well described.

    Naming Consistency5/5

    Every tool uses the waha_ prefix followed by a consistent snake_case verb_noun pattern (list_sessions, get_chat, send_text, mark_chat_read). No mixed conventions or casing deviations.

    Tool Count4/5

    18 tools is at the upper edge but each maps to a concrete WhatsApp operation across sessions, chats, messages, and contacts. Nothing is clearly redundant, though a couple of convenience tools (waha_get_me, waha_take_screenshot) could be folded into existing calls.

    Completeness4/5

    Session lifecycle (create/start/stop/list/get), chat reading, message sending across three media types, and presence/contact lookups are covered. Gaps remain: no session delete/logout despite stop hinting data is retained, and no message deletion or edit, which agents may need for full lifecycle control.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables WhatsApp automation through MCP protocol, allowing users to manage sessions, send messages, handle groups/communities, and access contacts through natural language interactions with AI agents.
      5 npm
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      OpenWA MCP server that bridges AI agents to the OpenWA WhatsApp API, exposing 40 tools for sessions, messages, contacts, groups, and webhooks so agents can read and send WhatsApp messages through a self-hosted OpenWA gateway.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP-compatible AI clients to work with self-hosted, linked WhatsApp accounts by exposing eight tools for listing sessions, chats, contacts and groups, reading message history, checking numbers, inspecting account details, and sending text messages.
      MIT