WhatsApp MCP Server

WhatsApp MCP 服务

一个使用 FastMCP 提供 Model Context Protocol（MCP）接口、用于与 WhatsApp Business API 交互的服务。

简介

WhatsApp MCP 服务是一个 Python 实现，可让 Claude 等大模型通过 GreenAPI 使用 WhatsApp 功能。它利用 FastMCP 提升性能、改善开发体验，并提供更简洁的实现。

功能

• 消息：向 WhatsApp 联系人发送文本消息
• 群组管理：创建群组、列出成员、添加或移除参与者
• 会话管理：管理 WhatsApp API 会话
• 聊天记录：获取聊天列表和消息历史记录

WhatsApp API 客户端

本项目使用 whatsapp-api-client-python 库与 WhatsApp 交互。客户端提供对 WhatsApp Cloud API 的访问权限，使用该 API 需要 GreenAPI 账户。

环境变量

本项目使用环境变量进行配置：

• GREENAPI_ID_INSTANCE：你的 GreenAPI 实例 ID
• GREENAPI_API_TOKEN：你的 GreenAPI API 令牌

你可以在环境中设置这些变量，也可以使用提供的 .env 文件（请参阅安装说明）。

安装

# Clone the repository
git clone https://github.com/yourusername/whatsapp-mcp-server.git
cd whatsapp-mcp-server

# Install dependencies
pip install -e .

# Set up environment variables
cp .env-template .env
# Edit the .env file with your GreenAPI credentials

使用方法

运行 MCP 服务：

# Run the MCP server on default host (127.0.0.1) and port (8000)
whatsapp-mcp

# Specify host and port
whatsapp-mcp --host 0.0.0.0 --port 9000

调试：

whatsapp-mcp --debug

该服务使用 Model Context Protocol（MCP）进行通信，使用 FastMCP 运行时，可通过 HTTP 或 WebSockets 访问。

可用工具

• open_session：打开新的 WhatsApp 会话
• send_message：向聊天发送消息
• get_chats：获取聊天列表
• create_group：创建新的 WhatsApp 群组
• get_group_participants：获取群组参与者

FastMCP API 参考

WhatsApp MCP 服务使用 FastMCP 提供 WebSocket 和 HTTP 端点：

• WebSocket：ws://localhost:8000/mcp
• HTTP：http://localhost:8000/mcp

你可以使用 curl 等工具直接测试 API：

# List available tools
curl -X POST http://localhost:8000/mcp/listTools

# Call a tool
curl -X POST http://localhost:8000/mcp/callTool \
  -H "Content-Type: application/json" \
  -d '{"name": "open_session", "arguments": {}}'

如何将其添加到 Claude Code

若要向 Claude 添加 WhatsApp 服务，请使用 claude mcp add 命令：

# Add the WhatsApp MCP server
$ claude mcp add whatsapp -- whatsapp-mcp

# List existing MCP servers - Validate that the server is running
claude mcp list

# Start claude code
claude

与 Claude 配合使用

WhatsApp MCP 服务运行后，你就可以在对话中通过 Claude 与其交互：

使用 WhatsApp 进行身份验证

Login to WhatsApp

发送消息

Send the "Hello" message to John Doe

与 Claude Desktop 配合使用

若要在 Claude Desktop 中使用 WhatsApp MCP 服务，需要将其添加到 claude_desktop_config.json 文件中：

使用 pip 安装（推荐）

"mcpServers": {
  "whatsapp": {
    "command": "python",
    "args": ["-m", "whatsapp_mcp"]
  }
}

使用可执行文件

"mcpServers": {
  "whatsapp": {
    "command": "whatsapp-mcp"
  }
}

使用 Docker

"mcpServers": {
  "whatsapp": {
    "command": "docker",
    "args": ["run", "--rm", "-i", "-e", "GREENAPI_ID_INSTANCE=your_instance_id", "-e", "GREENAPI_API_TOKEN=your_api_token", "whatsapp-mcp-server"]
  }
}

启动 Claude Desktop 前，请确保通过环境变量或 .env 文件设置 GreenAPI 凭据。

命令行选项

WhatsApp MCP 服务接受以下命令行参数：

• --debug：提高详细程度以便调试
• --host：服务绑定的主机（默认值：127.0.0.1）
• --port：服务绑定的端口（默认值：8000）

调试

调试 MCP 服务：

• 使用 MCP 检查器：npx @modelcontextprotocol/inspector whatsapp-mcp
• 在 Claude Desktop 日志目录中查看日志（macOS 上通常为 ~/Library/Logs/Claude/）
• 访问 http://localhost:8000 上的 FastMCP Web 界面，查看交互式 API 文档

开发

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
flake8 src/

# Run type checking
mypy src/

本项目使用现代化的 pyproject.toml 配置，其中包含：

• 运行应用所需的核心依赖项
• 通过 pip install -e ".[dev]" 安装的开发依赖项

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。