📱 WhatsApp MCP — Удаленный HTTP/SSE сервер

Сервер протокола контекста модели (MCP) для WhatsApp, созданный с помощью whatsapp-web.js и TypeScript. Поддерживает как локальный stdio (Claude Desktop), так и удаленный HTTP/SSE (Claude.ai Remote MCP) режимы.

⚠️ Условия использования WhatsApp — ВАЖНО

Прочитайте это перед использованием данного проекта.

Условия использования и Политика допустимого использования WhatsApp запрещают использование неофициальных инструментов автоматизации на личных или бизнес-аккаунтах.

🚫 Действия, которые приведут к БЛОКИРОВКЕ вашего номера:

✅ Более безопасные практики:

• Используйте выделенный/тестовый номер телефона, а не личный

• Пишите только тем контактам, которые дали согласие

• Поддерживайте низкую частоту сообщений, имитирующую человеческую активность

• Не открывайте публичный доступ к вашим /sse или REST эндпоинтам без защиты API_KEY

• Не используйте это для маркетинга, массовых рассылок или любой коммерческой деятельности в больших масштабах

• Используйте 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. Сканирование QR-кода

Откройте браузер и перейдите по адресу:

http://localhost:3000/qr

Отсканируйте QR-код с помощью WhatsApp → Связанные устройства → Привязка устройства.

🔌 API эндпоинты

🛠️ Доступные инструменты MCP

🔐 Опционально: Аутентификация через Bearer Token

Защитите ваши REST эндпоинты, установив переменную окружения 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 → Settings → Integrations → Remote MCP, вставьте:

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

☁️ Развертывание на Render

1. Отправьте этот репозиторий на GitHub (см. шаги Git ниже)

2. Перейдите на render.com → New → Web Service

3. Подключите ваш репозиторий GitHub

4. Настройте:

   • Build Command: npm install && npm run build

   • Start Command: npm run start:remote

   • Environment: NODE_ENV=production

   • Optional: API_KEY=yoursecretkey

5. Разверните и скопируйте ваш URL https://your-app.onrender.com

Вставьте в Claude Remote MCP:

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

⚠️ Примечание: Данные сессии WhatsApp (.wwebjs_auth) не сохраняются между развертываниями на Render. Используйте Render Disk или повторно сканируйте QR-код после каждого развертывания.

📦 npm скрипты

📄 Рекомендации по .gitignore

Убедитесь, что ваш .gitignore включает:

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

🔒 Никогда не коммитьте .wwebjs_auth/ — он содержит учетные данные вашей сессии WhatsApp.

🔧 Переменные окружения

🤝 Участие в разработке

Pull-запросы приветствуются! Для крупных изменений, пожалуйста, сначала откройте issue.

📜 Лицензия

MIT — используйте ответственно и в соответствии с Условиями использования WhatsApp.

💡 Совет: Установите расширение GitLens в VS Code для гораздо более удобной работы с Git — история коммитов, blame, сравнения и многое другое.