WhatsApp MCP 服务器

一个提供模型上下文协议 (MCP) 接口以使用 FastMCP 与 WhatsApp Business API 进行交互的服务器。

简介

WhatsApp MCP 服务器是一个 Python 实现，它通过 GreenAPI 使像 Claude 这样的语言模型能够与 WhatsApp 功能进行交互。它利用 FastMCP 提升性能、改善开发体验并实现更简洁的代码实现。

特性

• 消息传递：向 WhatsApp 联系人发送文本消息
• 群组管理：创建群组、列出成员、添加/移除参与者
• 会话处理：管理 WhatsApp API 会话
• 聊天历史：检索聊天列表和消息历史

WhatsApp API 客户端

此项目使用 whatsapp-api-client-python 库与 WhatsApp 进行交互。客户端提供了对 WhatsApp Cloud 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 代码中

要将 WhatsApp 服务器添加到 Claude，请使用 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 桌面版一起使用

要将 WhatsApp MCP 服务器与 Claude 桌面版一起使用，您需要将其添加到 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 之前，将您的 GreenAPI 凭证设置为环境变量或在 .env 文件中设置。

命令行选项

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

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

调试

对于 MCP 服务器的调试：

• 使用 MCP 检查器: npx @modelcontextprotocol/inspector whatsapp-mcp
• 在您的 Claude Desktop 日志目录中查看日志（在 macOS 上通常是 ~/Library/Logs/Claude/）
• 访问 FastMCP 网页界面 http://localhost:8000 以获取交互式 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 文件。