waha-fast-mcp
Exposes a local WAHA WhatsApp HTTP API instance as MCP tools for managing sessions, listing chats and messages, marking chats read, setting typing status, taking screenshots, sending text/images/files, and checking contacts or profile pictures.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@waha-fast-mcp Send a WhatsApp message to +15551234567 saying I'll be late"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 <--> WhatsAppTools
Area | Tools |
Sessions |
|
Chats and messages |
|
Sending |
|
Contacts |
|
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 .envSet 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-mcpUse 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_KEYin 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_fileaccept local paths, so the stdio server can read files with the agent process's permissions.SKILL.mdis 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 toolswaha_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
Scored across 18 tools
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.
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.
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.
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
Related MCP Connectors
WhatsMCP connects Claude and other MCP-compatible AI agents directly to WhatsApp. Send and receive text, images, documents, and voice notes; manage groups (create, add/remove members, promote admins); look up contacts and profiles; follow channels; and read call and message history — all through a standard MCP interface. For voice use cases, WhatsMCP offers SIP-based calling plans (inbound-only, or full inbound/outbound) so AI voice agents can answer and place WhatsApp calls, plus low-latency WebSocket integrations with voice agent providers like ElevenLabs. Multiple WhatsApp accounts can be paired and managed per workspace, with webhook support for real-time inbound message delivery to your own infrastructure.
Hosted WhatsApp MCP server: read, search and reply to your own WhatsApp chats from your AI.
Drive WhatsApp from any MCP client: pair devices, send text and media, manage contacts and groups.
Link a WhatsApp number by QR code and use it from Claude or ChatGPT via MCP.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceEnables 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-
- AlicenseBqualityBmaintenanceEnables sending messages, images, documents and more on WhatsApp directly from any MCP-compatible AI, with tools for chat management, groups, and webhooks.371MIT
- FlicenseNot gradedqualityDmaintenanceOpenWA 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.-
- AlicenseNot gradedqualityCmaintenanceEnables 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