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

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

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

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

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

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

✅ 更安全的操作实践：

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

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

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

• 不要 在没有 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 端点

🛠️ 可用的 MCP 工具

🔐 可选：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 脚本

📄 .gitignore 建议

确保您的 .gitignore 包含：

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

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

🔧 环境变量

🤝 贡献

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

📜 许可证

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

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