WhatsApp MCP 服务器

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

介绍

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

Related MCP server: MCP Evolution API

特征

• 消息传递：向 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

服务器使用模型上下文协议 (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

要将 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 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 检查器： 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 文件。