WhatsApp MCP服务器

WAHA WhatsApp MCP服务器

TypeScript 模型上下文协议 标准 WhatsApp服务器通过统一的WAHA后端。它公开了28个工具 消息、联系人、媒体、转录、语音生成、自动语音备忘 回复、消息存储搜索和每次对话的媒体自动化。

建筑学

MCP client → this package → unified backend /api (:8200)
                                  ├─ PostgreSQL message store
                                  ├─ WAHA live proxy
                                  ├─ transcription and TTS providers
                                  └─ media analysis/archive worker

MCP服务器只与经过身份验证的 /api 外观。它无法连接 直接发送到WAHA、数据库、Nextcloud或模型提供商。仅局域网管理 有意排除档案审查和LLM提供者管理的途径。

本次发布的目标 waha-backend 承诺 46acc32 或兼容的较新版本。

安装

Claude 代码

claude mcp add waha-whatsapp -- \
  env WAHA_API_URL=http://your-server:8200/api \
      WAHA_API_KEY=your-backend-api-key \
  npx -y @marcos-heidemann/waha-mcp-server

MCP JSON配置

{
  "mcpServers": {
    "waha-whatsapp": {
      "command": "npx",
      "args": ["-y", "@marcos-heidemann/waha-mcp-server"],
      "env": {
        "WAHA_API_URL": "http://your-server:8200/api",
        "WAHA_API_KEY": "your-backend-api-key"
      }
    }
  }
}

配置

较老的 WAHA_STORE_* 和 WAHA_TRANSCRIPTION_* 不再使用变量。 这些服务在统一后端后面配置。

联系人标识符

聊天定位工具使用稳定 contactId:

• 人：带有国家代码的电话号码，例如 5521999999999.
• 组：稳定组JID结束于 @g.us.
• 遗产 @c.us 和 @lid 后端所在的路由上仍接受别名 支持他们。
• 导入的聊天ID以结尾 @import 使用消息读取/搜索，但不使用 后端聊天摘要路由。

使用 whatsapp_list_contacts 以发现标识符。

工具（28）

媒体自动化设置

whatsapp_media_settings_update 支持：

• captureEnabled
• analyzeImages
• analyzeDocuments
• whatsappReplyEnabled
• includeMediaInRecap
• archiveMode: off, review，或 auto
• fixedNextcloudFolderId：整数或 null
• archiveConfirmationEnabled
• allowSensitiveProcessing
• askOnReview

对话设置与后端范围的终止开关相结合。始终检查 返回警告或呼叫 whatsapp_automation_health 在假设某个特征之前 活跃。当前的公共卫生/警告合同没有暴露全球大门 用于回顾纳入或审查问题。

当前后端限制

• 公共后端发送路由不实现手动报价回复。 供应 replyTo 返回MCP错误，不发送任何内容。
• whatsapp_forward_message 重新发送存储的文本。它不保存媒体， 发件人归因或WhatsApp的Forwarded标签。
• 一些当前的GOWS媒体仍然以存储类型公开 chat；类型过滤器可能 直到后台公共API切换到 normalized_type.
• 公共聊天摘要不完整 @lid 别名感知。阅读/搜索更安全 迁移历史的选择。
• 导入的发件人身份仅为历史记录，从中省略 whatsapp_list_contacts；进口 *@import 聊天支持阅读/搜索，但不支持实时 阅读收据或聊天摘要。
• 持久的分阶段媒体预览、Nextcloud文件夹发现、存档审查/操作， 并且电机/LLM配置仍然是仅限操作员的管理功能。

开发和验证

npm ci
npm test                  # hermetic unit + backend-contract tests
npm run build
npm pack --dry-run

通过推送与包版本完全匹配的标签来部署发布， 例如 v2.4.0发布工作流重复单元测试和之前的构建 使用存储库密钥发布到npm。

现场测试需要 WAHA_API_URL 和 WAHA_API_KEY:

npm run test:live                         # read-only suites
WAHA_TEST_LEVEL=2 npm run test:live       # includes self-chat writes
WAHA_TEST_LEVEL=3 npm run test:live       # includes configured contact writes

默认的测试和CI路径从不与WhatsApp联系。

安全

• 将后端API密钥视为密码；永远不要承诺。
• 通过非官方的WhatsApp API发送可以触发防空控制。保持 自动化范围狭窄，速度有限。
• 媒体和聊天导出可能包含敏感数据。之前审查自动化策略 实现分析、回复或存档。
• 旋转Git历史记录中以前出现的任何凭据。

许可证

麻省理工学院