PyWA MCP Server

PyWA MCP服务器

全面的模型上下文协议（MCP）服务器，使用PyWA库公开完整的WhatsApp Business API功能。

特性

此MCP服务器提供 18 WhatsApp工具 分为四类：

消息工具（12）

• 文本和媒体: send_message, send_image, send_video, send_document, send_audio, send_sticker
• 地点和联系方式: send_location, request_location, send_contact
• 交互: send_reaction, remove_reaction, upload_media

交互式工具（2）

• 交互式消息: send_message_with_buttons, send_message_with_list

模板工具（2）

• 模板消息: send_template, get_templates

状态工具（2）

• 消息状态: mark_message_as_read, indicate_typing

设置

1. 安装依赖项：

   uv sync

1. 配置WhatsApp凭据：

   cp .env.example .env
   # Edit .env with your WhatsApp Cloud API credentials

1. 运行服务器：

   # Production mode
   uv run python server.py

   # Development mode with Web UI (recommended for testing)
   uv run fastmcp dev --ui-port 6275 server.py

配置

设置这些环境变量：

• WHATSAPP_PHONE_ID -您的WhatsApp商务电话号码ID
• WHATSAPP_TOKEN -您的WhatsApp Cloud API访问令牌

从你的 Meta开发人员控制台.

开发与测试

Web UI（推荐用于开发）

使用FastMCP Inspector交互式测试您的WhatsApp工具：

uv run fastmcp dev --ui-port 6275 server.py

打开http://localhost:6275在浏览器中：

• 查看所有15+WhatsApp工具
• 测试消息、按钮、列表、模板
• 查看实时API调用和响应
• 使用全面的错误消息进行调试

使用真实WhatsApp进行测试

1. 从获取WhatsApp Business API凭据 Meta开发人员控制台
2. 在Meta Developer控制台中添加测试电话号码
3. 使用Web UI向测试编号发送消息
4. 验证消息是否出现在WhatsApp中

Claude桌面集成

快速设置（一个命令）

直接在Claude Desktop配置中安装：

{
  "mcpServers": {
    "pywa-whatsapp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Jem-HR/pywa-mcp-server.git",
        "pywa-mcp-server"
      ],
      "env": {
        "WHATSAPP_PHONE_ID": "your_phone_id",
        "WHATSAPP_TOKEN": "your_token"
      }
    }
  }
}

这会自动下载并运行服务器，而无需手动安装。

手动配置

1. 找到Claude Desktop配置文件：

- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - 视窗: %APPDATA%\Claude\claude_desktop_config.json

1. 添加服务器配置：

   {
     "mcpServers": {
       "pywa-whatsapp": {
         "command": "uv",
         "args": [
           "run",
           "python",
           "/path/to/pywa-mcp-server/server.py"
         ],
         "env": {
           "WHATSAPP_PHONE_ID": "your_phone_number_id",
           "WHATSAPP_TOKEN": "your_whatsapp_cloud_api_token"
         }
       }
     }
   }

1. 重新启动克劳德桌面

1. 验证连接： 寻找🔨 Claude Desktop中的锤子图标

在Claude Desktop中使用WhatsApp工具

连接后，您可以要求Claude：

发送消息：

Send a WhatsApp message to +1234567890 saying "Hello from Claude!"

创建交互式按钮：

Send a WhatsApp message with buttons asking "Are you available?" 
with Yes/No options to +1234567890

构建菜单列表：

Create a WhatsApp menu for a restaurant with sections for Main Courses 
and Beverages, send to +1234567890

显示打字指示器：

Show typing indicator for WhatsApp message ID wamid.XXX to let the user 
know I'm preparing a response

发送媒体：

Send an image from URL https://example.com/image.jpg with caption 
"Check this out!" to +1234567890

使用模板：

Send the "welcome_message" template in English to +1234567890

Claude中可用的WhatsApp工具

Claude可以使用这些WhatsApp功能：

📝 消息传递（12个工具）：

• send_message -带有页眉/页脚的短信
• send_image -带字幕的图像
• send_video -带字幕的视频
• send_document -具有自定义名称的文件
• send_audio -音频消息
• send_sticker -WebP贴纸
• send_location -GPS坐标
• request_location -向用户询问位置
• send_contact -联系人卡片
• send_reaction -表情符号反应
• remove_reaction -消除反应
• upload_media -将文件上传到WhatsApp

🎛️ 交互式（2个工具）：

• send_message_with_buttons -最多3个回复按钮
• send_message_with_list -带部分的选择列表

📋 模板（2个工具）：

• send_template -预先批准的模板消息
• get_templates -列出可用模板

⚡ 状态（2个工具）：

• mark_message_as_read -将邮件标记为已读
• indicate_typing -显示打字指示器

建筑

服务器使用模块化架构：

• 服务器.py -使用FastMCP框架的主MCP服务器
• 工具/messaging.py -文本、媒体、位置、联系人和反应工具
• 工具/交互式.py -按钮、列表、目录和流消息工具
• 工具/模板.py -模板消息传递和身份验证工具

所有工具都遵循一致的模式：

• 异步实现以获得最佳性能
• 具有成功/错误响应的全面错误处理
• 直接映射到PyWA库方法
• 全类型安全和参数验证

工具示例

send_message

向WhatsApp用户发送短信。

{
  "to": "+1234567890",
  "text": "Hello from PyWA MCP Server!",
  "preview_url": true,
  "reply_to_message_id": "optional_message_id"
}

send_button_message

发送带有回复按钮的交互式消息。

{
  "to": "+1234567890",
  "text": "Choose an option:",
  "buttons": [
    {"id": "option1", "title": "Option 1"},
    {"id": "option2", "title": "Option 2"}
  ],
  "header": "Quick Actions",
  "footer": "Select one option"
}

send_template

发送预先批准的模板消息。

{
  "to": "+1234567890",
  "template": "hello_world",
  "language": "en",
  "components": [
    {
      "type": "body",
      "parameters": [
        {"type": "text", "text": "John Doe"}
      ]
    }
  ]
}

故障排除

常见问题

❌ “缺少必需的环境变量”

• 确保 .env 文件存在 WHATSAPP_PHONE_ID 和 WHATSAPP_TOKEN
• 从Meta Developer控制台检查值是否正确

❌ “无法从pywa.types导入名称'X'”

• 跑 uv sync 更新依赖关系
• PyWA版本必须>=3.0.0

❌ “401未经授权”来自WhatsApp API

• 验证您的 WHATSAPP_TOKEN 是最新的，并且具有适当的权限
• Meta Developer控制台中的检查令牌尚未过期

❌ Claude Desktop不显示工具

• 检查 claude_desktop_config.json 语法是有效的JSON
• 确保文件路径是绝对的，而不是相对的
• 配置更改后重新启动Claude Desktop
• 寻找🔨 锤子图标确认连接

❌ “键入指示器失败”

• indicate_typing 需要传入消息中的有效消息ID
• 不能与任意消息ID一起使用-必须来自实际收到的WhatsApp消息

调试模式

通过设置环境变量启用详细日志记录：

export PYTHONPATH=/path/to/pywa-mcp-server
LOGLEVEL=DEBUG uv run python server.py

获取帮助

• 检查 Pywa文档 获取WhatsApp API的详细信息
• 审查 Meta开发人员控制台 用于API设置
• 在集成Claude Desktop之前，使用Web UI单独测试工具

许可证

麻省理工学院