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 提問並繼續工作！

🚀 完整設置指南：

快速配置示例：

{
  "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. 零停機！⚡

📖 另請參閱：

• - 完整設置指南
• - 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 格式：

注意：電話號碼應去掉 + 前綴。

💻 使用示例

發送文本消息

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