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.
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_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.