AI导哈

WhatsApp MCP服务器

一个基于whatsapp-web.js和TypeScript构建的WhatsApp模型上下文协议服务器，支持本地stdio和远程HTTP/SSE模式，适用于个人自动化和开发测试。

  • by PONMANIAN-SA
  • TypeScript
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 PONMANIAN-SA/Whatsapp_mcp

使用说明

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

WhatsApp的模型上下文协议（MCP）服务器，用 whatsapp-web.js 以及TypeScript。
支持两者 本地stdio （克劳德桌面）和 远程HTTP/SSE （第ai条远程MCP）模式。

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

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

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

🚫 将使您的号码被禁止的操作：

违规 风险等级
发送批量/垃圾邮件 🔴 即时禁令
将消息自动转换为未知数字 🔴 即时禁令
使用非官方WhatsApp客户端（如 whatsapp-web.js) 🟠 高风险
大规模删除联系人或组数据 🟠 高风险
未经用户同意发送消息 🔴 即时禁令
在个人号码上全天候运行机器人 🟡 中等风险
批量发送媒体/文件 🟠 高风险

✅ 更安全的做法：

  • 使用一个 专用/测试电话号码，不是你的个人号码
  • 只有消息 已选择加入的联系人
  • 保持低消息频率和人性化
  • 做 不 暴露你的 /sse 或REST端点公开，无需 API_KEY 保护
  • 做 不 将其用于营销、推销或任何大规模的商业信息传递
  • 使用 WhatsApp商务API（官方） 用于生产/商业用途

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

🗂️ 项目结构

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帐户（使用测试号！）
  • 安装了谷歌Chrome或Chromium（由Puppeteer内部使用）

1.安装依赖项

npm install

2.构建TypeScript

npm run build

3.启动服务器

远程HTTP/SSE模式 （第ai条远程MCP）：

npm run start:remote

开发模式 （无需构建，使用 ts-node):

npm run dev:remote

stdio模式 （克劳德桌面）：

npm start

4.扫描二维码

打开浏览器并转到：

http://localhost:3000/qr

使用WhatsApp扫描二维码→ 已关联设备→ 链接设备.

🔌 API终点

方法 路径 描述
GET / 或 /health 健康检查+WhatsApp状态
GET /qr 二维码HTML页面（扫描验证）
GET /qr?format=json JSON格式的原始QR数据
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端点 （克劳德远程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 从特定聊天中获取消息

🔐 可选：承载令牌认证

通过设置 API_KEY 环境变量：

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

☁️ 部署以渲染

  1. 将此仓库推送到GitHub（请参阅下面的Git步骤）
  2. 首选 render.com → New → Web服务
  3. 连接您的GitHub存储库
  4. 配置：
    • 构建命令： npm install && npm run build
    • 启动命令： npm run start:remote
    • 环境： NODE_ENV=production
    • 可选： API_KEY=yoursecretkey
  5. 部署和复制您的 https://your-app.onrender.com 统一资源定位符

粘贴到Claude Remote MCP：

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

⚠️ 注： WhatsApp会话数据(.wwebjs_auth)确实如此 不 在渲染部署中保持不变。使用一个 渲染磁盘 或在每次部署后重新扫描二维码。

📦 npm脚本

命令 描述
npm run build 将TypeScript编译为 dist/
npm start 启动stdio MCP服务器
npm run start:remote 启动HTTP/SSE远程服务器
npm run dev 开发stdio服务器（ts节点，无构建）
npm run dev:remote 开发远程服务器（ts节点，无构建）
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身份验证的可选承载令牌
NODE_ENV development 设置为 production 渲染上

🤝 贡献

欢迎拉取请求！对于重大更改，请先打开一个问题。

📜 许可证

麻省理工学院-负责任地使用并遵守WhatsApp的服务条款。

💡 提示： 安装 GitLens扩展 在VS Code中，您将获得更丰富的Git体验——提交历史、责备、比较等。

相关 MCP