使用说明
WhatsApp WAHA MCP服务器
最小模型上下文协议（MCP）服务器 WAHA（WhatsApp HTTP API）.
23个工具•300行•98%的测试覆盖率•无SDK依赖
特性
23工具 分为6类：
会话（4个工具）
list_sessions-列出所有会话start_session-开始新会话stop_session-停止会话get_session-获取会话状态
消息传递（5个工具）
send_text-发送短信send_image-发送图片send_file-发送文件/文档send_location-发送位置react_to_message-用表情符号做出反应
聊天（4个工具）
list_chats-列出所有聊天记录get_messages-获取聊天信息delete_chat-删除聊天archive_chat-存档聊天
组（5个工具）
create_group-创建组list_groups-列出组get_group-获取群组信息add_participants-添加成员remove_participants-删除成员
联系人（3个工具）
list_contacts-列出联系人get_contact-获取联系信息check_number-检查号码是否存在
出席（2个工具）
set_presence-设置在线/离线set_typing-设置打字指示器
安装
先决条件：
- Python 3.10+
- 紫外线 包管理器
- WAHA实例（例如，WAHA.devlike.pro）
安装：
git clone https://github.com/FarisHijazi/whatsapp-waha-mcp.git
cd whatsapp-waha-mcp
uv venv && source .venv/bin/activate
uv pip install -e .
配置
创建 .env 文件：
WAHA_BASE_URL=https://waha.devlike.pro
WAHA_API_KEY=your-api-key-here
使用Claude Desktop
增添 claude_desktop_config.json:
macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
窗户： %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"whatsapp-waha": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/whatsapp-waha-mcp",
"run",
"whatsapp-waha-mcp"
],
"env": {
"WAHA_BASE_URL": "https://waha.devlike.pro",
"WAHA_API_KEY": "your-api-key-here"
}
}
}
}
示例用法
问克劳德：
"List all my WhatsApp sessions"
"Start a new session called 'my-phone'"
"Send 'Hello!' to +1234567890"
"Create a group 'Team' with +1111111111, +2222222222"
"List all my chats"
发展
安装开发依赖项：
uv pip install -e ".[dev]"
运行测试：
pytest # Run all tests
pytest -v # Verbose mode
pytest --cov # With coverage report
所有34个测试都使用mocking-不需要外部API调用！
项目结构
whatsapp-waha-mcp/
├── src/whatsapp_waha_mcp/
│ ├── __init__.py # Package init
│ └── server.py # MCP server (300 lines)
├── tests/
│ ├── __init__.py
│ └── test_server.py # Unit tests (34 tests, 98% coverage)
├── pyproject.toml # Project config
├── pytest.ini # Test config
└── README.md # This file
技术细节
- 框架： FastMCP（轻量级MCP框架）
- HTTP客户端： httpx（异步HTTP库）
- 运输： STDIO（标准MCP通信）
- 协议： JSON-RPC 2.0
- 依赖关系：
mcp,httpx,python-dotenv - 开发依赖关系：
pytest,pytest-asyncio,pytest-mock,pytest-cov - 测试覆盖范围： 98%（34次通过测试）
为什么没有SDK？
WAHA是一个简单的REST API。直接使用httpx是：
- ✅ 更简单 -没有额外的依赖关系
- ✅ 更透明 -你看到底是怎么回事
- ✅ 更易于维护 -少了一层要调试
- ✅ 更小的代码库 -300线对700+线
整个HTTP层只是一个干净的函数：
async def api_call(method: str, path: str, **kwargs) -> dict[str, Any]:
"""Make WAHA API request."""
headers = {"X-API-Key": API_KEY} if API_KEY else {}
response = await client.request(method, f"{BASE_URL}/api{path}", headers=headers, **kwargs)
response.raise_for_status()
return response.json() if response.status_code != 204 else {"success": True}
许可证
MIT许可证-请参阅 许可证
