waha-mcp

🚀 WAHA MCP 服务器

WAHA MCP 服务器将强大的 WAHA（WhatsApp HTTP API） 与 Claude Desktop 等 AI 助手相连接，通过模型上下文协议（MCP）实现无缝的 WhatsApp 自动化。

🚀 快速开始

WAHA MCP 服务器能将 WAHA (WhatsApp HTTP API) 与 Claude Desktop 等 AI 助手连接起来，借助模型上下文协议（MCP）实现 WhatsApp 的自动化操作。

✨ 主要特性

• 📱 全面的 WhatsApp 控制 - 发送/接收消息、管理聊天、创建群组
• 🎯 63 种工具 - 涵盖会话、消息、联系人、群组和交互式工作流的全面 API
• 🔄 智能媒体处理 - 语音/视频自动转换，支持 URL 和本地文件
• 🤖 原生 AI 支持 - 专为通过 MCP 集成大语言模型而构建
• 🔒 安全可靠 - 基于环境的 API 密钥管理
• ⚡ 快速稳定 - 由 TypeScript 驱动，具备强大的错误处理能力

📦 安装指南

1. 克隆并安装

git clone https://github.com/dudu1111685/waha-mcp.git
cd waha-mcp
npm install
npm run build

2. 设置环境变量

创建一个 .env 文件或导出变量：

export WAHA_API_KEY="your-api-key-here"
export WAHA_URL="http://localhost:3001"  # 可选，默认为 localhost:3001

⚙️ 配置

Claude Desktop

添加到 claude_desktop_config.json：

• Linux：~/.config/claude/claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "waha": {
      "command": "node",
      "args": ["/absolute/path/to/waha-mcp/dist/index.js"],
      "env": {
        "WAHA_API_KEY": "your-api-key-here",
        "WAHA_URL": "http://localhost:3001"
      }
    }
  }
}

Cline / VS Code

添加到你的 Cline MCP 设置（~/.vscode/mcp.json 或工作区设置）：

{
  "mcpServers": {
    "waha": {
      "command": "node",
      "args": ["/absolute/path/to/waha-mcp/dist/index.js"],
      "env": {
        "WAHA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code（自主开发）

🤖 开启真正的自主 AI 开发： Claude 无需在需要用户输入时停止，而是可以通过 WhatsApp 提问并继续工作！

🚀 完整设置指南：CLAUDE_CODE_SETUP.md

快速配置示例：

{
  "mcpServers": {
    "waha": {
      "command": "node",
      "args": ["/path/to/waha-mcp/dist/index.js"],
      "env": {
        "WAHA_API_KEY": "your-key",
        "USER_WHATSAPP_CHAT_ID": "1234567890@c.us"
      }
    }
  },
  "globalInstructions": "When you need user input during development, use ask_user_via_whatsapp tool. Never stop and wait for manual console input."
}

工作原理：

1. Claude 遇到问题 → 通过 WhatsApp 提问
2. 你从手机回复
3. Claude 立即继续工作
4. 零停机！⚡

📖 另请参阅：

• CLAUDE_CODE_SETUP.md - 完整设置指南
• CLAUDE_CODE_INSTRUCTIONS.md - AI 助手使用示例

其他 MCP 客户端

使用 mcporter CLI 进行快速测试：

mcporter call 'waha-mcp.waha_list_sessions()'
mcporter call 'waha-mcp.waha_send_text(chatId: "1234567890@c.us", text: "Hello from MCP!")'

🧰 工具参考

📂 类别

// Claude Code 正在构建一个功能，需要澄清问题
const reply = await ask_user_via_whatsapp({
  question: "Should I use REST or GraphQL for the API?",
  chatId: "1234567890@c.us",
  timeoutMinutes: 30
});
// 用户从手机回复："Use GraphQL"
// Claude Code 继续使用 GraphQL 进行实现

📚 聊天 ID 格式

了解 WhatsApp ID 格式：

| 类型 | 格式 | 示例 | |------|--------|---------| | 用户 | {phone}@c.us | 1234567890@c.us | | 群组 | {id}@g.us | 1234567890-1234567890@g.us | | 频道 | {id}@newsletter | 1234567890@newsletter | | 动态 | status@broadcast | status@broadcast |

注意：电话号码应去掉 + 前缀。

💻 使用示例

发送文本消息

mcporter call 'waha-mcp.waha_send_text(
  chatId: "1234567890@c.us",
  text: "Hello from WAHA MCP!"
)'

从 URL 发送图片

mcporter call 'waha-mcp.waha_send_image(
  chatId: "1234567890@c.us",
  imageUrl: "https://example.com/photo.jpg",
  caption: "Check this out!"
)'

创建群组并添加参与者

# 创建群组
mcporter call 'waha-mcp.waha_create_group(
  name: "Team Chat",
  participants: ["1111111111@c.us", "2222222222@c.us"]
)'

# 添加更多参与者
mcporter call 'waha-mcp.waha_add_group_participants(
  chatId: "{group_id}@g.us",
  participants: ["3333333333@c.us"]
)'

列出所有聊天

mcporter call 'waha-mcp.waha_list_chats()'

🧪 开发

以监听模式运行

npm run dev  # 文件更改时重新编译

运行测试

npm test

生产环境构建

npm run build

📚 详细文档

如需详细文档，请参阅 docs 文件夹：

• 会话管理
• 消息发送指南
• 群组管理
• 媒体处理
• 故障排除

🤝 贡献

欢迎贡献代码！请随时提交问题或拉取请求。

1. 分叉仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开拉取请求

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

🙏 致谢

• WAHA (WhatsApp HTTP API) - 此集成的核心
• 模型上下文协议 - 支持原生 AI 工具集成
• Anthropic - 提供 Claude Desktop 和 MCP SDK