WhatsApp MCP 服务器

一个提供模型上下文协议（MCP）接口的服务器，通过FastMCP与WhatsApp Business API进行交互。

简介

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

特性

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

WhatsApp API 客户端

该项目使用whatsapp-api-client-python库与WhatsApp进行交互。客户端提供了对WhatsApp云API的访问，需要一个GreenAPI账户才能使用。

环境变量

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

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

您可以在环境中设置这些变量，或者使用提供的.env文件（参见安装说明）。

安装

# 克隆仓库
git clone https://github.com/yourusername/whatsapp-mcp-server.git
cd whatsapp-mcp-server

# 安装依赖
pip install -e .

# 设置环境变量
cp .env-template .env
# 使用您的GreenAPI凭证编辑.env文件

使用方法

运行MCP服务器：

# 在默认主机(127.0.0.1)和端口(8000)上运行MCP服务器
whatsapp-mcp

# 指定主机和端口
whatsapp-mcp --host 0.0.0.0 --port 9000

调试：

whatsapp-mcp --debug

服务器使用模型上下文协议（MCP）进行通信，并且在使用FastMCP时可以通过HTTP或WebSocket访问。

可用工具

• 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：

# 列出可用工具
curl -X POST http://localhost:8000/mcp/listTools

# 调用工具
curl -X POST http://localhost:8000/mcp/callTool \
  -H "Content-Type: application/json" \
  -d '{"name": "open_session", "arguments": {}}'

如何将其添加到Claude Code

要将WhatsApp服务器添加到Claude，使用claude mcp add命令：

# 添加WhatsApp MCP服务器
$ claude mcp add whatsapp -- whatsapp-mcp

# 列出现有的MCP服务器 - 验证服务器是否正在运行
claude mcp list

# 启动Claude
claude

使用Claude

一旦WhatsApp MCP服务器运行起来，您就可以在对话中使用Claude与其进行交互：

与WhatsApp认证

登录到WhatsApp

发送消息

向John Doe发送“Hello”消息

使用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之前，将您的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 Web界面http://localhost:8000以获得交互式API文档

开发

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

# 运行代码检查
flake8 src/

# 运行类型检查
mypy src/

该项目使用现代的pyproject.toml配置，包括：

• 运行应用程序所需的核心依赖
• 使用pip install -e ".[dev]"可用的开发依赖

许可证

本项目根据MIT许可证发布 - 详情请参阅LICENSE文件。