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 Cloud API 的访问，使用该 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 或 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：

# 列出可用工具
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 code
claude

与 Claude 一起使用

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

使用 WhatsApp 验证

登录到 WhatsApp

发送消息

向 John Doe 发送 "Hello" 消息

与 Claude Desktop 一起使用

要将 WhatsApp MCP 服务器与 Claude Desktop 一起使用，您需要将其添加到您的 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 inspector: npx @modelcontextprotocol/inspector whatsapp-mcp
• 在您的 Claude Desktop 日志目录中查看日志（通常在 macOS 上为 ~/Library/Logs/Claude/）
• 访问 FastMCP Web 界面，地址为 http://localhost:8000，以获取交互式 API 文档

开发

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

# 运行测试
pytest

# 运行 linting
flake8 src/

# 运行类型检查
mypy src/

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

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

许可证

本项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。