waMCP (Delltrak)

🟢 WA MCP

The first WhatsApp integration built natively for AI Agents.

Full MCP server exposing WhatsApp as discoverable tools, resources, and real-time notifications.

Quick Start • Features • Tools • Architecture • Configuration • Docker • Contributing

______________________________________________________________________

🤖 什么是WA MCP？

WA-MCP 是一个使用TypeScript构建的WhatsApp MCP服务器，它使AI代理能够通过 模型上下文协议。它支持这两种功能 百利 （WhatsApp网络）和 Meta Cloud API 作为双通道后端，可与 码头工人 在一个命令中。

您的代理连接一次并自动发现 63工具, 10资源，以及 12个实时事件 --零配置，零REST包装，零粘合代码。

Your AI Agent ←→ MCP Protocol ←→ WA MCP ←→ WhatsApp

您的代理只需编写HTTP客户端、解析webhook有效负载并将端点手动映射到工具即可 连接并离开.开箱即用 克劳德, 谷歌ADK, LangChain，以及任何与MCP兼容的AI代理框架。

💡 主控程序 （模型上下文协议）是将AI代理连接到工具和数据的开放标准。WA MCP通过流式HTTP和stdio传输以本地方式使用MCP。

______________________________________________________________________

🚀 快速开始

使用Docker执行一个命令

docker compose up

就是这样。WA MCP+Redis，准备就绪 http://localhost:3000/mcp.

或在本地运行

# Prerequisites: Node.js >= 22, Redis running
npm install
cp .env.example .env

# Development (stdio transport)
npm run dev

# Production (HTTP transport)
npm run build && npm start

连接您的代理

🐍 Google ADK (Python)

from google.adk.tools.mcp_tool import McpToolset

tools = McpToolset(url="http://localhost:3000/mcp")

# Agent auto-discovers 63 WhatsApp tools
# wa_create_instance, wa_send_text, wa_send_image, ...

🦜 LangChain

from langchain_mcp import McpToolkit

toolkit = McpToolkit(server_url="http://localhost:3000/mcp")
tools = toolkit.get_tools()

💻 Claude Desktop

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": ["path/to/wa-mcp/dist/index.js"],
      "env": {
        "WA_TRANSPORT": "stdio",
        "WA_REDIS_URL": "redis://localhost:6379"
      }
    }
  }
}

______________________________________________________________________

✨ 特性

______________________________________________________________________

🛠️ 工具

WA MCP暴露 63工具 跨越9个领域。所有工具都使用 wa_ 前缀。

📋 Instance Management (8 tools)

💬 Messaging (17 tools)

💭 Chat Management (6 tools)

👥 Groups (14 tools)

📇 Contacts (5 tools)

👤 Profile (5 tools)

📢 Status / Stories (3 tools)

📰 Newsletter (3 tools)

📞 Calls (1 tool)

______________________________________________________________________

📖 资源

资源通过以下方式公开WhatsApp的只读状态 whatsapp:// URI：

______________________________________________________________________

📡 实时通知

事件通过SSE（服务器发送事件）推送到代理：

______________________________________________________________________

🏗️ 建筑

┌─────────────────────────────────────────────┐
│              AI Agent Runtime               │
│    (Google ADK, Claude, LangChain, ...)     │
└──────────────────┬──────────────────────────┘
                   │  MCP Streamable HTTP
┌──────────────────▼──────────────────────────┐
│              WA MCP Server                  │
│                                             │
│  ┌────────────────────────────────────────┐ │
│  │  Layer 1 — MCP Transport (HTTP/stdio) │ │
│  ├────────────────────────────────────────┤ │
│  │  Layer 2 — MCP Core                   │ │
│  │  63 Tools │ 10 Resources │ 12 Events  │ │
│  ├────────────────────────────────────────┤ │
│  │  Layer 3 — Services                   │ │
│  │  Instance Manager │ Queue │ Dedup     │ │
│  ├────────────────────────────────────────┤ │
│  │  Layer 4 — Channel Abstraction        │ │
│  │  ┌──────────────┐ ┌────────────────┐  │ │
│  │  │   Baileys    │ │   Cloud API    │  │ │
│  │  │  (WebSocket) │ │    (HTTPS)     │  │ │
│  │  └──────────────┘ └────────────────┘  │ │
│  └────────────────────────────────────────┘ │
│       SQLite (Drizzle)    BullMQ (Redis)    │
└─────────────────────────────────────────────┘
                   │
                   ▼  WebSocket / HTTPS
          WhatsApp Servers

双通道设计

两个后端实现相同的功能 ChannelAdapter 界面。你的代理不知道或不关心哪个是活动的——这些工具的工作原理是相同的。

______________________________________________________________________

⚙️ 配置

复制 .env.example 到 .env 并配置：

______________________________________________________________________

🐳 码头工人

生产

docker compose up -d

服务：

• wa-mcp --端口上的MCP服务器 3000
• 瑞迪斯 --具有AOF持久性的BullMQ后端

健康检查

curl http://localhost:3000/health

{
  "status": "ok",
  "uptime": 3600,
  "instances": { "total": 3, "connected": 2, "disconnected": 1 },
  "version": "1.0.0"
}

资源需求

______________________________________________________________________

📁 项目结构

src/
├── index.ts                     # Entry point (HTTP/stdio)
├── constants.ts                 # Defaults and limits
├── server/mcp.ts                # MCP server setup
├── tools/                       # 🔧 63 MCP tools (9 files)
├── resources/                   # 📖 10 MCP resources (8 files)
├── notifications/events.ts      # 📡 12 event types
├── channels/
│   ├── channel.interface.ts     # ChannelAdapter contract
│   ├── baileys/                 # Baileys implementation
│   └── cloud-api/               # Cloud API implementation
├── services/
│   ├── instance-manager.ts      # Instance lifecycle
│   ├── message-queue.ts         # BullMQ rate limiting
│   ├── dedup.ts                 # Message deduplication
│   └── media.ts                 # Media handling
├── db/
│   ├── schema.ts                # Drizzle table definitions
│   └── client.ts                # SQLite connection
├── schemas/                     # Zod validation (9 files)
└── types/                       # TypeScript definitions

______________________________________________________________________

🗺️ 路线图

• \[x\] 第一阶段 --基础：Baileys适配器、短信、QR认证、实例管理
• \[x\] 第2阶段 --完整消息传递：所有媒体类型、数据消除、反应、编辑、转发
• \[x\] 第三期 --群组、联系人、个人资料、状态/故事、时事通讯
• \[x\] 阶段4 -云API适配器：双通道统一接口
• \[x\] 阶段5 --强化：错误恢复、CI/CD、测试、文档、v1.0版本
• \[x\] 第6阶段 --Baileys v7升级，LID支持，联系人同步，消息持久化

______________________________________________________________________

🤝 贡献

欢迎投稿！以下是代码库的组织方式：

1. 每个域一个文件 --工具、资源、模式和通道都有特定于域的文件
2. Zod模式适用于一切 --所有工具输入都使用严格的Zod模式进行验证 src/schemas/
3. 两个适配器 -新功能应该在Baileys中实现，并在Cloud API中进行存根
4. 分层体系结构 --工具→ 服务→ 频道。无跨层导入。
5. 结构化日志记录 --使用皮诺，永远不要 console.log

# Development
npm run dev          # Start with stdio transport
npm run build        # Type-check + compile
npx tsc --noEmit     # Type-check only

______________________________________________________________________

📄 许可证

麻省理工学院——随心所欲。

______________________________________________________________________

Built for the agentic era.

Stop writing REST wrappers. Let your agent discover WhatsApp.