Skip to main content
Glama

📱 WhatsApp MCP — 远程 HTTP/SSE 服务器

WhatsApp 模型上下文协议 (MCP) 服务器,基于 whatsapp-web.js 和 TypeScript 构建。 支持 本地 stdio (Claude Desktop) 和 远程 HTTP/SSE (Claude.ai Remote MCP) 两种模式。


⚠️ WhatsApp 服务条款 — 重要提示

在使用本项目前请阅读此内容。

WhatsApp 的 服务条款 和 可接受使用政策 禁止 在个人或商业账户上使用非官方自动化工具。

🚫 会导致您的号码被封禁的操作:

违规行为

风险等级

发送群发/垃圾消息

🔴 立即封禁

自动向陌生号码发送消息

🔴 立即封禁

使用非官方 WhatsApp 客户端 (如 whatsapp-web.js)

🟠 高风险

大规模抓取联系人或群组数据

🟠 高风险

未经用户同意发送消息

🔴 立即封禁

在个人号码上 24/7 运行机器人

🟡 中风险

大规模发送媒体/文件

🟠 高风险

✅ 更安全的操作实践:

  • 使用 专用/测试手机号码,而非您的个人号码

  • 仅向 已授权的联系人 发送消息

  • 保持消息发送频率较低,模拟人类行为

  • 不要 在没有 API_KEY 保护的情况下公开暴露您的 /sse 或 REST 端点

  • 不要 将此用于营销、销售轰炸或任何大规模商业消息发送

  • 生产/商业用途请使用 WhatsApp Business API (官方)

🔒 本项目仅供个人自动化和开发/测试使用。 作者不对因滥用导致的任何账户封禁或法律后果负责。


Related MCP server: WhatsApp MCP Server

🗂️ 项目结构

whatsapp-mcp/
├── src/
│   ├── index.ts          # stdio MCP server (Claude Desktop)
│   ├── remote.ts         # HTTP/SSE MCP server (Remote MCP + REST API)
│   └── send_message.ts   # CLI script to send a single message
├── dist/                 # Compiled JavaScript (auto-generated, do not edit)
├── .wwebjs_auth/         # WhatsApp session data (⚠️ keep this gitignored!)
├── .wwebjs_cache/        # Puppeteer browser cache (gitignored)
├── package.json
├── tsconfig.json
├── render.yaml           # Render.com deployment config
├── start-remote.bat      # Windows quick-start script
└── README.md

🚀 快速开始

前置要求

  • Node.js v18+ 和 npm

  • 一个 WhatsApp 账户(请使用测试号码!)

  • 已安装 Google Chrome 或 Chromium(Puppeteer 内部使用)


1. 安装依赖

npm install

2. 构建 TypeScript

npm run build

3. 启动服务器

远程 HTTP/SSE 模式 (Claude.ai Remote MCP):

npm run start:remote

开发模式 (无需构建,使用 ts-node):

npm run dev:remote

stdio 模式 (Claude Desktop):

npm start

4. 扫描二维码

打开浏览器并访问:

http://localhost:3000/qr

使用 WhatsApp 扫描二维码 → 已关联设备 → 关联新设备。


🔌 API 端点

方法

路径

描述

GET

/ 或 /health

健康检查 + WhatsApp 状态

GET

/qr

二维码 HTML 页面(扫描以进行身份验证)

GET

/qr?format=json

JSON 格式的原始二维码数据

GET

/tools

列出所有可用的 MCP 工具

GET

/tools/status

WhatsApp 连接状态

POST

/tools/send-message

发送 WhatsApp 消息

GET

/tools/chats

列出最近的聊天

GET

/tools/contacts

列出联系人

GET

/tools/messages/:chatId

获取聊天记录

POST

/tools/invoke

通用 MCP 工具调用

GET

/sse

MCP SSE 端点 (Claude Remote MCP)

POST

/messages

MCP POST 端点 (与 /sse 配对使用)


🛠️ 可用的 MCP 工具

工具

描述

whatsapp_status

检查连接状态

whatsapp_send_message

发送文本消息

whatsapp_send_media

发送图片/视频/文档

whatsapp_get_contacts

列出所有联系人

whatsapp_get_groups

列出所有群组

whatsapp_get_group_info

获取群组详情和成员

whatsapp_create_group

创建新群组

whatsapp_get_chats

获取最近的聊天

whatsapp_get_messages

获取特定聊天的消息


🔐 可选:Bearer Token 认证

通过设置 API_KEY 环境变量来保护您的 REST 端点:

API_KEY=mysecretkey npm run start:remote

在所有请求中包含该令牌:

curl -H "Authorization: Bearer mysecretkey" http://localhost:3000/tools/status

🌐 使用 ngrok 测试 (公共 HTTPS)

  1. 安装 ngrok

  2. 启动您的服务器:npm run start:remote

  3. 在新终端中运行:ngrok http 3000

  4. 复制生成的 URL (例如 https://xxxx.ngrok-free.app)

在 Claude.ai → 设置 → 集成 → 远程 MCP 中,粘贴:

https://xxxx.ngrok-free.app/sse

☁️ 部署到 Render

  1. 将此仓库推送到 GitHub (参考下方的 Git 步骤)

  2. 前往 render.com → New → Web Service

  3. 连接您的 GitHub 仓库

  4. 配置:

    • 构建命令: npm install && npm run build

    • 启动命令: npm run start:remote

    • 环境: NODE_ENV=production

    • 可选: API_KEY=yoursecretkey

  5. 部署并复制您的 https://your-app.onrender.com URL

粘贴到 Claude Remote MCP 中:

https://your-app.onrender.com/sse

⚠️ 注意: WhatsApp 会话数据 (.wwebjs_auth) 在 Render 部署之间不会持久保存。请使用 Render Disk 或在每次部署后重新扫描二维码。


📦 npm 脚本

命令

描述

npm run build

将 TypeScript 编译到 dist/

npm start

启动 stdio MCP 服务器

npm run start:remote

启动 HTTP/SSE 远程服务器

npm run dev

开发 stdio 服务器 (ts-node,无需构建)

npm run dev:remote

开发远程服务器 (ts-node,无需构建)

npm run send

CLI:发送单条消息

npm run qr

在终端显示二维码


📄 .gitignore 建议

确保您的 .gitignore 包含:

node_modules/
dist/
.wwebjs_auth/
.wwebjs_cache/
.env
*.bat

🔒 切勿提交 .wwebjs_auth/ — 它包含您的 WhatsApp 会话凭据。


🔧 环境变量

变量

默认值

描述

PORT

3000

HTTP 服务器端口

HOST

0.0.0.0

服务器绑定地址

API_KEY

(空)

REST 认证的可选 Bearer 令牌

NODE_ENV

development

在 Render 上设置为 production


🤝 贡献

欢迎提交 Pull Request!对于重大更改,请先开启一个 Issue。


📜 许可证

MIT — 请负责任地使用,并遵守 WhatsApp 的服务条款。


💡 提示: 在 VS Code 中安装 GitLens 扩展 以获得更丰富的 Git 体验 — 包括提交历史、代码责备 (blame)、对比等。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A Node.js application that connects WhatsApp Web with AI models through the Model Context Protocol, enabling automated messaging, contact management, and group chat functionality through AI-driven workflows.
      37 npm
      46
      MIT
    • A
      license
      C
      quality
      D
      maintenance
      A Model Context Protocol server that connects your personal WhatsApp account to AI agents like Claude, enabling them to search messages, view contacts, retrieve chat history, and send messages via WhatsApp.
      7
      76
      ISC
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      A Model Context Protocol server that integrates with WaPulse WhatsApp Web API, enabling users to send messages, manage groups, handle files, and perform various WhatsApp operations programmatically.
      3 npm
      1
      -