WhatsApp MCP Stack Stream

Сервер WhatsApp MCP, построенный на транспорте Streamable HTTP, с использованием Baileys для подключения к WhatsApp, с веб-интерфейсом администрирования и двунаправленным потоком медиа (загрузка и скачивание).

Ключевые особенности:

• Транспорт: Streamable HTTP на /mcp

• Движок: Baileys

• Админ-панель: QR, статус, выход, настройки времени выполнения, просмотр истории чатов

• Медиа: эндпоинты загрузки + хостинг /media + MCP-инструмент скачивания

Быстрый старт (Docker)

# build and run

docker compose build

docker compose up -d

Сервер будет доступен по адресам:

• Админ-панель: http://localhost:3003/admin

• MCP-эндпоинт: http://localhost:3003/mcp

• Медиа-файлы: http://localhost:3003/media/<filename>

Related MCP server: lingtai-whatsapp

DNS на хостах с --iptables=false

На некоторых NAS и усиленных хостах (например, Synology с dockerd --iptables=false) встроенный DNS-прокси Docker (127.0.0.11) не имеет правил iptables DNAT и отказывает в соединениях внутри контейнеров.

Решение: скопируйте resolv.conf.example в resolv.conf и добавьте в том переопределение:

cp resolv.conf.example resolv.conf

Затем добавьте в локальный docker-compose.override.yml (не коммитьте его):

services:
  mcp-whatsapp:
    volumes:
      - ./resolv.conf:/etc/resolv.conf:ro

docker compose up автоматически подхватит переопределение.

Настройки выполнения

Настройки можно изменять в админ-панели; они сохраняются в SETTINGS_PATH (по умолчанию — MEDIA_DIR/settings.json).

Админ-панель

Админ-консоль с настройками времени выполнения, привязкой по QR, просмотрщиком истории чатов, экспортом и статусом.

Поддерживаемые настройки:

• media_public_base_url

• upload_max_mb

• upload_enabled

• max_files_per_upload

• require_upload_token

• upload_token

• auto_download_media

• auto_download_max_mb

Аутентификация

Встроенная аутентификация ещё не реализована. В продакшене используйте шлюз с принудительной проверкой подлинности. Проект хорошо работает за authmcp-gateway:

https://github.com/loglux/authmcp-gateway

API загрузки медиа

Base64 JSON:

curl -X POST http://localhost:3003/api/upload \
  -H "Content-Type: application/json" \
  -d {filename:photo.jpg,mime_type:image/jpeg,data:<base64>}

Multipart (рекомендуется для больших файлов):

curl -X POST http://localhost:3003/api/upload-multipart \
  -F "file=@/path/to/file.jpg"

Оба метода возвращают url и (если настроено) publicUrl.

Отправка локальных файлов через send_media

Каталог ./files/ в корне проекта монтируется в контейнер по пути /app/files. Положите туда любой файл и сразу используйте его — перезапуск контейнера не нужен:

# On host:
cp report.pdf /path/to/whatsapp-mcp-stream/files/

# In send_media:
media_path: /app/files/report.pdf

Для источника в виде URL передайте media_url напрямую в send_media или stage_media — сервер сам скачает файл, без base64.

Авторизация загрузки (необязательно)

Если require_upload_token=true, передавайте токен одним из способов:

• x-upload-token: <token>

• Authorization: Bearer <token>

MCP-транспорт

Сервер представляет Streamable HTTP на /mcp.

Типовый поток:

1. POST /mcp с JSON-RPC initialize

2. Используйте возвращаемый заголовок IDs-session-id для последующих запросов

3. POST /mcp для вызова инструментов

Примечание: клиенты должны отправлять Accept: application/json, text/event-stream при initialize.

Смоук-тест

Быстрый регрессионный смоук-тест MCP-инструментов:

npm run smoke:mcp

Необязательная целевая цель:

MCP_BASE_URL=http://localhost:3003 npm run smoke:mcp

Инструменты MCP

Аутентификация

Контакты

Чаты

Сообщения

Медиа

Дополнительно

Заметки о восстановлении

В этом сервисе есть намеренный обходной механизм для восстановления состояния сессии Baileys/WhatsApp.

Почему он существует:

• В продакшене мы наблюдали случаи, когда контейнер оставался живым, MCP продолжал отвечать, но сессия WhatsApp была фактически полностью уничтожена.

• Самыми распространёнными индикаторами были ошибки Baileys: failed to find key ... to decode mutation и failed to sync state from version.

• В таком состоянии ручной перезапуск контейнера часто восстанавливал работоспособность.

Текущее поведение:

• При сигнале повреждения состояния приложения, сервис сначала пробует мягкое восстановление через forceResync().

• Если повторяется однотипный сбой в течение временного интервала, происходит эскалация до внутреннего перезапуска WhatsApp-клиента.

• При отключениях, таких как Connection Terminated, сервис запускает сторожевой таймер и, если сокет не вернулся в состояние open, эскалирует до внутреннего перезапуска.

• Цикл перезапуска защищён от вложенных блокировок, поэтому отключения могут быть автоматически восстановлены без ручного перезапуска и необходим.

• Недавние наблюдения в проде показывают повторные отключения сокета (428 Connection Terminated, 503 Stream Errored) автоматически возвращаются в состояние open.

• Отдельный эндпоинт /healthz возвращает 503 только когда сервис по-настоящему застрял вне допустимого окна восстановления.

• Healthcheck Docker использует /healthz, поэтому контейнер перезапускается только после того, как внутреннее восстановление получит шанс сработать.

Эти механизмы сокращают необходимость вмешательства оператора и повышают устойчивость к часто встречающимся сбоям сессий WhatsApp/Baileys.

Лицензия

MIT

Персистентность

Чаты и сообщения сохраняются в локальную базу данных SQLite, размещённую вместе с сессией.

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

Дополнительная диагностика транспорта:

• POST-запросы /mcp теперь записывают события жизненного цикла запроса в logs/mcp-whatsapp.log

• сюда входят поступление запроса, диспетчеризация транспорта, завершение transport.handleRequest, а также HTTP finish / close

• по этим журналам можно определить, возникает ли задержка до того, как ответ покидает whatsapp-mcp-stream, или уже после — на стороне шлюза/клиента

API истории чатов

Просматривайте сохранённые чаты и сообщения через:

GET /api/chats?limit=50&offset=0&q=<search> — постраничный список чатов, опционально фильтруется по имени.

GET /api/chats/:jid/messages?limit=50&offset=0 — постраничные сообщения чата (сначала новые).

Оба эндпоинта используются вкладкой Чаты в админ-интерфейсе.

Экспорт

Экспортируйте чат (JSON + необязательно скачанные медиафайлы) через:

GET /api/export/chat/:jid?include_media=true

Если include_media=true, ZIP-архив включает файлы, уже скачанные через download_media. Он не загружает недостающие медиафайлы из WhatsApp.