Whatsapp MCP Extended

WhatsApp MCP扩展

WhatsApp的扩展模型上下文协议（MCP）服务器 41工具 -高级消息传递、组管理、webhooks、状态等。

WhatsApp MCP

什么是新的（vs原创）

建筑

┌─────────────────────┐     ┌─────────────────────┐     ┌─────────────────────┐
│   whatsapp-bridge   │     │   whatsapp-mcp      │     │    webhook-ui       │
│   (Go + whatsmeow)  │◄────│   (Python + MCP)    │     │   (HTML/JS SPA)     │
│   Port: 8080        │     │   Ports: 8081,8082  │     │   Port: 8089        │
└─────────────────────┘     └─────────────────────┘     └─────────────────────┘
         │                           │
         ▼                           ▼
    ┌─────────────────────────────────────┐
    │           SQLite (store/)           │
    │  messages.db │ whatsapp.db          │
    └─────────────────────────────────────┘

快速开始

Docker（推荐）

git clone https://github.com/felixisaac/whatsapp-mcp-extended
cd whatsapp-mcp-extended

docker network create n8n_n8n_traefik_network
docker-compose up -d

# Scan QR code to authenticate
docker-compose logs -f whatsapp-bridge

Claude桌面/光标集成

添加到MCP配置(claude_desktop_config.json 或光标设置）：

{
  "mcpServers": {
    "whatsapp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/whatsapp-mcp-extended/whatsapp-mcp-server", "python", "main.py"]
    }
  }
}

MCP工具（共41个）

消息传递

聊天和消息

联系人

群组

出席和简介

通讯（频道）

API设计理念

响应数据优先级 完整的上下文，解释最少。参见 元数据_哲学.md 用于：

• 为什么我们包括原始数据而不是预先计算的信号
• 我们如何减少消费LLM的代币浪费
• 响应结构示例（消息、聊天、联系人）
• 设计规则：原始事实、可计数指标、排除空值

太长，读不下去了 在一个响应中获取所有联系信息，而不是重复查询。LLM从原始数据+指标中推断语气、紧迫性和关系。

Webhook系统

用于传入消息的实时HTTP webhooks，具有：

• 触发器：all、chat\_\_id、发件人、关键字、media_type
• 匹配：exact，contains，正则表达式
• 安全：HMAC-SHA256签名
• 重试：指数级回退

访问webhook用户界面 http://localhost:8089

发展

手动设置

# Bridge (Go 1.25+)
cd whatsapp-bridge && go run main.go

# MCP Server (Python 3.11+)
cd whatsapp-mcp-server && uv sync && uv run python main.py

# Webhook UI
cd whatsapp-webhook-ui && python3 -m http.server 8089

预构建检查

cd whatsapp-mcp-server
uv run python check.py  # Catches errors before docker build

更新whatsmow

当你看到 Client outdated (405) 错误：

cd whatsapp-bridge
go get -u go.mau.fi/whatsmeow@latest
go mod tidy
docker-compose build whatsapp-bridge
docker-compose up -d whatsapp-bridge

端口

故障排除

邮件未送达

如果API返回成功，但消息显示单个复选标记：

docker-compose restart whatsapp-bridge
docker-compose logs --tail=10 whatsapp-bridge
# Should see: "✓ Connected to WhatsApp!"

二维码问题

docker-compose logs -f whatsapp-bridge
# Scan QR with WhatsApp mobile app

学分

叉链：

• 拉里斯/whatsapp mcp -原始MCP服务器（12个工具）
• 阿达姆鲁萨克/whatsapp -添加了webhooks、容器拆分、webhook UI
• 此仓库-添加了反应、编辑/删除、分组、民意调查、在线状态、新闻通讯（41个工具）

图书馆：

• 怎么回事 -转到WhatsApp Web API
• FastMCP -Python MCP SDK

社区致谢

几个分叉独立地解决了实际问题，他们的想法已被纳入这个回购中。到期信用：

如果你已经分叉了这个仓库并构建了一些有用的东西，打开一个PR或问题——好的想法应该向上游流动。

许可证

MIT许可证-请参阅 许可证 文件。