AI导哈

WhatsApp MCP服务器

一个生产就绪的模型上下文协议(MCP)服务器，通过WhatsApp Cloud API连接AI助手如Claude，实现消息发送、媒体管理、模板消息和实时Webhook接收。

  • by FredShred7
  • TypeScript
  • 本地部署
  • 24 星标
  • 更新于
在 GitHub 查看 FredShred7/whatsapp-mcp-server

使用说明

whatsapp mcp服务器

生产准备就绪 模型上下文协议（MCP）服务器 它将像克劳德这样的人工智能助手连接到 WhatsApp云API （Meta）。发送消息、管理对话、处理媒体、发送模板消息和接收实时webhooks——所有这些都是通过自然语言完成的。

为什么选择MCP服务器？

这是唯一建立在官方Meta WhatsApp Cloud API上的WhatsApp MCP服务器。

大多数面向开发人员的WhatsApp工具都依赖于非官方的浏览器自动化库(whatsapp-web.js)或逆向工程协议(whatsmeow, Baileys).这些做法违反了WhatsApp的服务条款，并带来了账户被禁止的真正风险。这个项目是不同的。

whatsapp mcp服务器 （这个项目） 非官方图书馆(whatsapp-web.js, whatsmeow, Baileys)
API类型 ✅ 官方Meta WhatsApp云API ❌ 非官方/逆向工程
账户禁令风险 ✅ 无--Meta已批准 ⚠️ 高-违反WhatsApp服务条款
账户类型 ✅ WhatsApp商业帐户 仅限个人帐户
正常运行时间可靠性 ✅ 元SLA支持的基础架构 ❌ WhatsApp更新时中断
可扩展性 ✅ 商业级，多代理就绪 ❌ 仅限一次会议
模板消息 ✅ 全力支持 ❌ 不可用
介质处理 ✅ 本机云API媒体端点 ⚠️ 需要解决方法
Webhook支持 ✅ Meta webhook官方活动 ❌ 民意调查/脆弱的听众
生产使用 ✅ 为生产而建 ❌ 建议仅供个人/爱好使用
长期可行性 ✅ 稳定的API版本 ❌ 取决于逆向工程是否保持最新状态

底线： 如果你正在构建个人实验之外的任何东西——客户支持、自动通知、业务工作流——请使用官方的API。此服务器为您提供该功能，打包为插入式MCP服务器。

特性

  • 发送所有消息类型 --文本、图像、视频、音频、文档、反应
  • 模板消息 --发送和列出已批准的WhatsApp Business模板，并提供完整的组件支持
  • 媒体管理 --上传、检索和删除媒体文件
  • 对话历史 --通过webhook在内存中存储最近的对话
  • 实时网络钩子 --接收传入消息和传递状态更新
  • 业务概况 --阅读并更新您的WhatsApp Business个人资料
  • 联系人查询 --根据WhatsApp验证电话号码
  • 费率限制处理 --自动指数退避重试逻辑
  • 类型安全 --带Zod输入验证的全类型TypeScript
  • Docker就绪 --包含多级Dockerfile和docker组合
  • 无需webhook即可工作 --只发送模式，不需要webhook服务器

建筑

┌─────────────────────────────────────────────────────────────┐
│                    AI Assistant (Claude)                      │
└──────────────────────────┬──────────────────────────────────┘
                           │ MCP Protocol (stdio)
                           │
┌──────────────────────────▼──────────────────────────────────┐
│                  whatsapp-mcp-server                         │
│                                                              │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────────┐  │
│  │  MCP Server │  │   Tools      │  │  WhatsApp Client  │  │
│  │  (stdio)    │◄─┤  messages    ├─►│  (Axios + retry)  │  │
│  │             │  │  contacts    │  └────────┬──────────┘  │
│  └─────────────┘  │  media       │           │              │
│                   │  templates   │           │ HTTPS        │
│  ┌─────────────┐  └──────────────┘           │              │
│  │  Webhook    │                             ▼              │
│  │  Server     │  ◄──── Incoming   ┌─────────────────────┐ │
│  │  (Express)  │       messages    │ WhatsApp Cloud API  │ │
│  └──────┬──────┘       & statuses  │  graph.facebook.com  │ │
└─────────│───────────────────────────┼─────────────────────┘ │
          │                           │                        │
          │ HTTP POST (Meta webhooks) │ HTTPS (send messages)  │
          │                           │                        │
     ┌────▼──────────────────────────▼──────────────┐
     │            WhatsApp Users                     │
     └────────────────────────────────────────────────┘

Webhook flow for incoming messages:
WhatsApp User → Meta Servers → POST /webhook → WhatsAppWebhook
→ in-memory conversation store → EventEmitter → MCP tools

先决条件

  1. Node.js 20+ — 下载
  2. 元开发人员帐户 — 创建一个
  3. WhatsApp商业应用 在Meta App仪表板中配置
  4. 电话号码ID 和 访问令牌 从您的WhatsApp应用程序设置
  5. （可选） 用于接收webhooks的公共HTTPS URL（本地开发使用ngrok）

快速开始

选项A——使用npx运行（不需要克隆）

该包裹运送了一个 whatsapp-mcp-server 二进制，所以使用它的最快方法是 让您的MCP客户端通过以下方式启动它 npx 并通过传递凭据 env （见 下面的客户端配置块):

npx -y @fredshred7/whatsapp-mcp-server

npx 按需下载并运行已发布的包——指向您的MCP客户端 完成它，你就完成了。跳转到 使用Claude Desktop 或 使用Claude代码.

选项B--从源代码克隆和构建

步骤1--克隆并安装：

git clone https://github.com/FredShred7/whatsapp-mcp-server.git
cd whatsapp-mcp-server
npm install

步骤2--配置凭据：

cp .env.example .env
# Edit .env with your WhatsApp credentials

步骤3——构建：

npm run build

步骤4——添加到克劳德桌面或克劳德代码 （见下文各节）

第五步——测试： 问克劳德： “发送WhatsApp消息至+15551234567，向克劳德问好！”

配置

所有配置都是通过环境变量进行的。复制 .env.example 到 .env 并填写数值。

变量 必填 描述
WHATSAPP_PHONE_NUMBER_ID 是 您的WhatsApp电话号码ID（来自Meta App仪表板>WhatsApp>API设置）
WHATSAPP_ACCESS_TOKEN 是 您的应用程序的永久访问令牌（在Meta app Dashboard中生成）
WHATSAPP_WEBHOOK_VERIFY_TOKEN Webhook 随机秘密字符串——必须与您在Meta App Dashboard中输入的内容匹配
WHATSAPP_APP_SECRET 推荐 Meta 应用密钥 （应用仪表板>设置>基本）。用于验证 X-Hub-Signature-256 在传入的webhooks上签名。强烈推荐在生产中使用。如果未设置，则跳过签名验证（并发出启动警告），因此本地开发仍然可以工作。
WHATSAPP_BUSINESS_ACCOUNT_ID 可选 WhatsApp商业帐户ID——列出电话号码和模板所需
WHATSAPP_API_VERSION 可选 WhatsApp Cloud API版本（默认： v21.0)
WEBHOOK_PORT 可选 传入webhook服务器的端口（默认：关闭）。设置为 3000 以启用
WEBHOOK_PATH 可选 webhooks的HTTP路径（默认： /webhook)
LOG_LEVEL 可选 记录详细程度： info 或 debug （默认值： info)

可用工具

工具 说明 关键参数
whatsapp_send_text 发送短信 to, text, preview_url?, reply_to_message_id?
whatsapp_send_image 发送带有可选标题的图像 to, image_url, caption?
whatsapp_send_video 发送带有可选字幕的视频 to, video_url, caption?
whatsapp_send_audio 发送音频消息 to, audio_url
whatsapp_send_document 发送文档/文件 to, document_url, caption?, filename?
whatsapp_send_reaction 使用表情符号回复消息 to, message_id, emoji
whatsapp_mark_read 将邮件标记为已读 message_id
whatsapp_list_conversations 列出最近的对话（需要webhook） limit?
whatsapp_get_conversation 获取联系人消息（需要webhook） phone_number, limit?
whatsapp_get_message_status 获取交付/读取状态（需要webhook） message_id
whatsapp_get_contact ⚠️ 传统/不受支持 --在WhatsApp上验证电话号码（见下面的注释） phone_number
whatsapp_get_business_profile 获取您的WhatsApp Business个人资料 --
whatsapp_update_business_profile 更新业务简介信息 about?, address?, description?, email?, websites?, vertical?
whatsapp_upload_media 从URL上传媒体，获取媒体ID media_url, mime_type, filename?
whatsapp_get_media_url 获取媒体的临时下载URL media_id
whatsapp_delete_media 删除上传的媒体 media_id
whatsapp_send_template 发送已批准的模板消息 to, template_name, language_code, components?
whatsapp_list_templates 列出可用的消息模板 limit?

⚠️ whatsapp_get_contact 是遗留的，预计不会在云API上工作。 它依赖于 POST /{phone-number-id}/contacts “联系检查”，这是一个 遗产的特征 WhatsApp On-Premises API -不是云API端点 后来被删除。每 Meta的On-Premises API Sunset, 最终的本地客户端版本 于2025年10月23日到期.联系人检查 WhatsApp云API（该服务器使用的API）中从未存在过 API 无等效联系人验证（即使在内部部署中，Meta也有 将其降级为始终返回 valid，因此结果不可信。)致 确定一个号码是否可以接收消息， 发送消息并检查 消息状态webhooks/错误代码 （例如。 131026 “消息 无法交付”）。该工具仅保留用于向后兼容性。

使用Claude Desktop

添加 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）。

推荐--通过以下方式运行已发布的包 npx （无需本地构建）：

{
  "mcpServers": {
    "whatsapp": {
      "command": "npx",
      "args": ["-y", "@fredshred7/whatsapp-mcp-server"],
      "env": {
        "WHATSAPP_PHONE_NUMBER_ID": "your_phone_number_id",
        "WHATSAPP_ACCESS_TOKEN": "your_access_token",
        "WHATSAPP_WEBHOOK_VERIFY_TOKEN": "your_verify_token",
        "WHATSAPP_APP_SECRET": "your_app_secret",
        "WHATSAPP_BUSINESS_ACCOUNT_ID": "your_business_account_id",
        "WEBHOOK_PORT": "3000"
      }
    }
  }
}

或者，运行本地构建 （克隆和 npm run build):

{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": ["/absolute/path/to/whatsapp-mcp-server/dist/index.js"],
      "env": {
        "WHATSAPP_PHONE_NUMBER_ID": "your_phone_number_id",
        "WHATSAPP_ACCESS_TOKEN": "your_access_token",
        "WHATSAPP_WEBHOOK_VERIFY_TOKEN": "your_verify_token",
        "WHATSAPP_APP_SECRET": "your_app_secret",
        "WHATSAPP_BUSINESS_ACCOUNT_ID": "your_business_account_id",
        "WEBHOOK_PORT": "3000"
      }
    }
  }
}

保存后重新启动Claude Desktop。您应该在工具面板中看到可用的WhatsApp工具。

使用Claude代码

添加到您的Claude Code MCP设置中(~/.claude/settings.json 或项目级别 .claude/settings.json).通过以下方式使用已发布的软件包 npx:

{
  "mcpServers": {
    "whatsapp": {
      "command": "npx",
      "args": ["-y", "@fredshred7/whatsapp-mcp-server"],
      "env": {
        "WHATSAPP_PHONE_NUMBER_ID": "your_phone_number_id",
        "WHATSAPP_ACCESS_TOKEN": "your_access_token",
        "WHATSAPP_WEBHOOK_VERIFY_TOKEN": "your_verify_token",
        "WHATSAPP_APP_SECRET": "your_app_secret",
        "WHATSAPP_BUSINESS_ACCOUNT_ID": "your_business_account_id",
        "WEBHOOK_PORT": "3000"
      }
    }
  }
}

或者使用CLI添加它：

claude mcp add whatsapp npx -y @fredshred7/whatsapp-mcp-server

Webhook设置

Webhooks允许您 接收 传入消息和传递状态更新。它们是可选的——MCP服务器在没有它们的情况下仅用于发送消息。

与ngrok合作进行本地开发

# 1. Install ngrok: https://ngrok.com/download
# 2. Start your webhook server
WEBHOOK_PORT=3000 npm run dev

# 3. In another terminal, expose it publicly
ngrok http 3000

# 4. Copy the HTTPS URL (e.g. https://abc123.ngrok.io)

在Meta App仪表板中配置

  1. 首选 元应用仪表板 >您的应用程序>WhatsApp>配置
  2. 集 回调URL 致： https://your-ngrok-url.ngrok.io/webhook
  3. 集 验证令牌 匹配您的 WHATSAPP_WEBHOOK_VERIFY_TOKEN
  4. 点击 验证并保存
  5. 订阅 消息 webhook字段

生产

对于生产，将此服务器部署在具有有效TLS证书的反向代理（nginx、Caddy等）后面。集 WEBHOOK_PORT 连接到您的内部端口，并通过HTTPS在端口443上公开它。

Docker部署

使用docker compose构建和运行

# Copy and fill in your credentials
cp .env.example .env

# Build and start
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

手动构建

# Build image
docker build -t whatsapp-mcp-server .

# Run (send-only, no webhook)
docker run --rm -i \
  -e WHATSAPP_PHONE_NUMBER_ID=xxx \
  -e WHATSAPP_ACCESS_TOKEN=xxx \
  whatsapp-mcp-server

# Run with webhook server
docker run --rm -i \
  -p 3000:3000 \
  --env-file .env \
  whatsapp-mcp-server

注： 当将Docker与Claude Desktop/Code一起使用时，MCP传输使用stdio。确保通过 -i （交互式），因此stdin/stdout保持连接。webhook端口与MCP传输是分开的。

发展

# Install dependencies
npm install

# Run with auto-reload
npm run dev

# Type-check only (no build)
npm run typecheck

# Build
npm run build

# Lint
npm run lint

# Run the test suite
npm test

# Re-run tests on change
npm run test:watch

项目结构

src/
├── index.ts              # Entry point — loads env, wires up components
├── server.ts             # MCP server — registers tools, handles requests
├── whatsapp/
│   ├── client.ts         # WhatsApp Cloud API client with retry logic
│   ├── types.ts          # TypeScript types and interfaces
│   └── webhook.ts        # Express webhook server + in-memory store
└── tools/
    ├── shared.ts         # Shared helpers: formatError + Zod->JSON Schema
    ├── messages.ts       # Send/receive message tools
    ├── contacts.ts       # Contact and business profile tools
    ├── media.ts          # Media upload/download/delete tools
    └── templates.ts      # Template message tools

test/                     # Vitest unit tests (schema, errors, webhook)

贡献

欢迎投稿！请阅读 贡献.md 有关报告错误、建议功能和提交pull请求的指南。

许可证

麻省理工学院 --版权所有（c）2025 FredShred7

相关 MCP