WAHA MCP Server

WAHA MCP服务器

适用于Claude Desktop和MCP兼容客户端的WhatsApp HTTP API集成

文档 • 安装 • 配置 • 🤖 Claude代码设置 • 工具参考

______________________________________________________________________

🚀 什么是WAHA MCP？

WAHA MCP服务器连接了强大的 WAHA（WhatsApp HTTP API） 借助Claude Desktop等人工智能助手，通过模型上下文协议（MCP）实现无缝的WhatsApp自动化。

✨ 主要特点

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

______________________________________________________________________

📋 先决条件

在开始之前，请确保您已经：

• Node.js 18+ - 点击此处下载
• 正在运行的WAHA实例 - 安装指南
• WAHA API密钥 -从您的WAHA仪表板生成

______________________________________________________________________

🛠️ 安装

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"  # Optional, defaults to localhost:3001

______________________________________________________________________

⚙️ 配置

克劳德桌面版

添加到 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代码

添加到您的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不会停止，它可以通过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. 克劳德提出了一个问题→ 通过WhatsApp提问
2. 您通过手机回复
3. 克劳德立即继续工作
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!")'

______________________________________________________________________

🧰 工具参考

📂 分类

Session Management (8 tools)

Authentication (3 tools)

Messaging (14 tools)

📤 媒体上传功能：

• ✅ 支持本地文件和URL
• ✅ 自动MIME类型检测
• ✅ 自动将视频/语音转换为WhatsApp格式
• ✅ 支持50多种文件类型
• ✅ 自动处理Base64编码

Chat Management (7 tools)

Contacts (5 tools)

Groups (13 tools)

Presence & Status (5 tools)

Labels (5 tools)

🆕 Interactive Workflows (1 tool)

用例示例：

// Claude Code is building a feature and needs clarification
const reply = await ask_user_via_whatsapp({
  question: "Should I use REST or GraphQL for the API?",
  chatId: "1234567890@c.us",
  timeoutMinutes: 30
});
// User replies from phone: "Use GraphQL"
// Claude Code continues with GraphQL implementation

它是如何工作的：

1. 通过WhatsApp发送您的问题
2. 用户新消息的投票
3. 收到回复文本后返回
4. 包括超时处理（默认值：60分钟）

非常适合：

• 🤖 Claude Code在工作流程中提问
• 💡 在您离开计算机时获取用户输入
• 🔄 构建真正的交互式人工智能自动化
• 📱 在AI继续工作的同时从手机接听

______________________________________________________________________

📚 聊天ID格式

了解WhatsApp ID格式：

注： 电话号码应排除 + 前缀。

______________________________________________________________________

🎯 快速示例

发短信

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: "",
  caption: "Check this out!"
)'

创建组并添加参与者

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

# Add more participants
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  # Recompiles on file changes

运行测试

npm test

为生产而建

npm run build

______________________________________________________________________

📖 文档

有关详细文档，请参阅 文档 文件夹：

• 会话管理
• 消息传递指南
• 组管理
• 媒体处理
• 故障排除

______________________________________________________________________

🤝 贡献

欢迎投稿！请随时提交问题或拉取请求。

1. 克隆该仓库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

______________________________________________________________________

📄 许可证

该项目根据 MIT许可证 -看看 许可证 文件以获取详细信息。

______________________________________________________________________

🙏 致谢

• WAHA（WhatsApp HTTP API） -这种整合的支柱
• 模型上下文协议 -实现AI原生工具集成
• Anthropic -适用于Claude Desktop和MCP SDK

______________________________________________________________________

建于❤️ 对于MCP社区