wazap-mcp

██╗    ██╗ █████╗ ███████╗ █████╗ ██████╗
██║    ██║██╔══██╗╚══███╔╝██╔══██╗██╔══██╗
██║ █╗ ██║███████║  ███╔╝ ███████║██████╔╝
██║███╗██║██╔══██║ ███╔╝  ██╔══██║██╔═══╝
╚███╔███╔╝██║  ██║███████╗██║  ██║██║
 ╚══╝╚══╝ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝

WhatsApp для вашего ИИ-агента. MCP-сервер, который предоставляет ваш аккаунт WhatsApp — чаты, сообщения, медиа, контакты, группы — через 22 инструмента, которые может вызывать любой MCP-клиент. Вход по коду сопряжения, без браузера, без перепродажи номеров телефонов, ~20 МБ ОЗУ.

Построен на Baileys, который говорит на мультиустройственном протоколе WhatsApp через WebSocket.

Начало работы

npm-пакет называется wazap-mcp; команда, которую он устанавливает, — wazap.

npx wazap-mcp setup

Это вся установка. Она связывает ваш аккаунт, находит MCP-клиентов, установленных на этой машине, записывает их конфигурацию и сообщает, что нужно перезапустить.

Или пусть это сделает ваш агент. Вставьте это:

Настрой мне WhatsApp: выполни npx wazap-mcp setup --agent и следуй тому, что он выведет.

Затем спросите агента: «Что я пропустил в WhatsApp сегодня?»

Ниже приведены шаги, которые setup выполняет за вас. Каждый из них — отдельная команда, если вы хотите выполнить её вручную.

npx wazap-mcp login показывает QR-код; отсканируйте его в Настройки → Связанные устройства → Привязать устройство. Нет камеры под рукой или связывание через SSH? npx wazap-mcp login --phone +15550100 выводит 8-значный код, который вы вводите в разделе Привязать по номеру телефона. В конце он спрашивает, может ли агент отправлять сообщения; ответ «нет», если вы не скажете «да», а npx wazap-mcp config writes on изменит это позже.

npx wazap-mcp connect claude-code записывает запись MCP для одного клиента. Остальные — в таблице под Подключение клиента.

npx wazap-mcp сам по себе безопасен для запуска: он выводит, где вы находитесь и что делать дальше, и не запускает сервер. Если что-то не так, npx wazap-mcp status — первое, что нужно запустить: он проверяет Node, каталог данных, блокировку, учётные данные и наличие новой версии, а рядом с каждой проблемой выводит исправление.

Подключение клиента

wazap connect <client> записывает запись за вас, сохраняя всё остальное в файле и делая резервную копию один раз перед первым изменением. --dry-run показывает, что он запишет.

Любой MCP-клиент работает одинаково: команда — npx -y wazap-mcp, транспорт — stdio. Скажите агенту сначала вызвать learn — он вернёт форматы идентификаторов, рабочие процессы и каждый код ошибки с указанием, что делать.

{
  "mcpServers": {
    "whatsapp": {
      "command": "npx",
      "args": ["-y", "wazap-mcp"]
    }
  }
}

Claude Desktop, Cursor и Gemini CLI принимают именно это. VS Code вкладывает это в servers и требует "type": "stdio" рядом с command. Codex CLI — это TOML:

[mcp_servers.whatsapp]
command = "npx"
args = ["-y", "wazap-mcp"]

Папка skills/ соответствует формату Agent Skills, поэтому Codex, Cursor и другие агенты, поддерживающие навыки, могут загрузить те же пять навыков.

Related MCP server: wa-bridge

Инструменты

Каждое сообщение возвращается с непустым text: медиа- и системные сообщения содержат заполнитель, например [image] caption, [voice message], [deleted] или [poll] Pizza or pasta?. Временные метки — ISO 8601 со смещением UTC машины, рядом человекочитаемый age, например 2h ago.

Навыки

wazap поставляется с пятью Agent Skills, которые обучают агента рабочим процессам, стоящим за инструментами, а не только самим инструментам:

Установите всё (сервер и навыки) как плагин Claude Code:

/plugin marketplace add razvangirgiz/wazap
/plugin install wazap@wazap

Или скопируйте skills/<name>/ в любой каталог навыков, который читает ваш агент.

Ошибки

Каждый сбой — это структурированный { error, message, fix }, а не трассировка стека, чтобы агент мог решить: повторить попытку, спросить пользователя или остановиться.

Каталог данных

Всё хранится в ~/.wazap (переопределяется с помощью --data-dir или WAZAP_DATA_DIR), создаётся с правами 0700, учётные данные записываются с правами 0600:

~/.wazap/
  auth/         WhatsApp credentials — treat this like a password
  media/        downloads from download_media
  history/      per-chat message history, so a restart is not amnesia
  store.json    chat-list snapshot
  server.lock   pid of the running server
  daemon.json   loopback endpoint a second wazap bridges to
  .env          optional settings, see .env.example

Запись учётных данных идёт во временный файл и затем переименовывается на место, поэтому убийство процесса во время записи не заставит вас заново связывать телефон.

Несколько клиентов одновременно

Claude Desktop, Claude Code и Cursor — каждый запускает собственный wazap. WhatsApp разрешает один сокет на привязанное устройство, поэтому они делят одну сессию, а не борются за неё. Первый wazap в каталоге данных владеет сессией и открывает MCP-эндпоинт на 127.0.0.1; каждый последующий подключается к нему через этот эндпоинт. Ничего настраивать не нужно, и ни один клиент не видит разницы. Владелец публикует <data-dir>/daemon.json (0600) со своим pid, своим портом и токеном, с которым мост аутентифицируется.

Мост обслуживает всё, что предоставляет владелец, поэтому владелец, запущенный с --read-only, делает каждого клиента доступным только для чтения, независимо от того, с какими флагами был запущен этот клиент.

Когда владелец выходит, мосты выходят вместе с ним, а следующий wazap, который запустит клиент, становится новым владельцем.

WAZAP_NO_SHARE=1 отключает это: второй wazap в том же каталоге завершается с кодом 2 и указывает pid уже запущенного. Явный --http — это самостоятельный сервер, а не мост, и ему отказывается так же.

Режим только для чтения

Запись — опциональна. login спрашивает один раз и сохраняет ответ в <data-dir>/.env; wazap config writes on|off меняет его, а один wazap config выводит все действующие настройки с указанием их источника.

WAZAP_READ_ONLY=1 или wazap serve --read-only вообще не регистрирует инструменты записи. Агент их никогда не видит, поэтому не может отправить сообщение с вашего номера даже по ошибке — полезно, когда привязанный аккаунт ваш личный.

Запись также ограничена по скорости до WAZAP_RATE_LIMIT в минуту (по умолчанию 20, 0 отключает). Отправка быстрее, чем человек, — это способ получить бан аккаунта.

HTTP-режим

WAZAP_READ_TOKEN=$(openssl rand -hex 32) \
WAZAP_WRITE_TOKEN=$(openssl rand -hex 32) \
npx wazap-mcp serve --http --host 0.0.0.0 --port 8766

Streamable HTTP на /mcp с проверкой работоспособности по /healthz. Два bearer-токена: токен чтения даёт инструменты чтения, токен записи дополнительно разблокирует инструменты записи, так что утёкший токен чтения никогда не сможет никому написать. wazap отказывается привязываться к адресу не-loopback без токена чтения.

Самостоятельный хостинг

Запустите wazap на собственном сервере, когда агент не на вашем ноутбуке: другая машина, VPS, инфраструктура клиента. Сессия остаётся на этом сервере; ничего не проходит через третьи стороны.

С systemd

npm install -g wazap-mcp
sudo useradd --system --home /var/lib/wazap --create-home wazap
sudo -u wazap WAZAP_DATA_DIR=/var/lib/wazap wazap login --phone +15550100   # pairing code works over SSH
sudo -u wazap tee /var/lib/wazap/.env >/dev/null <<END
WAZAP_READ_TOKEN=$(openssl rand -hex 32)
WAZAP_WRITE_TOKEN=$(openssl rand -hex 32)
END
sudo curl -fsSL https://raw.githubusercontent.com/razvangirgiz/wazap/main/deploy/wazap.service -o /etc/systemd/system/wazap.service
sudo systemctl enable --now wazap
curl -s http://127.0.0.1:8766/healthz

Юнит привязывается только к loopback. Поставьте TLS спереди с помощью двухстрочного deploy/Caddyfile (caddy run --config deploy/Caddyfile после редактирования имени хоста) или любого обратного прокси, затем укажите клиенту https://your-host/mcp с Authorization: Bearer <read or write token>.

С Docker

git clone https://github.com/razvangirgiz/wazap && cd wazap
printf 'WAZAP_READ_TOKEN=%s\nWAZAP_WRITE_TOKEN=%s\n' $(openssl rand -hex 32) $(openssl rand -hex 32) > .env
docker compose run --rm wazap login --phone +15550100   # once; the session lands in the wazap-data volume
docker compose up -d
curl -s http://127.0.0.1:8766/healthz

Контейнер публикует 8766 только на loopback; добавьте тот же TLS-прокси спереди. Обновление — это git pull && docker compose up -d --build; том сохраняет сессию.

Какие клиенты могут подключиться

Claude Code, Claude Desktop, Cursor, Codex, VS Code и любой клиент с полем «MCP URL + header» подключаются с bearer-токеном. Connectors в claude.ai требуют OAuth, а не статический токен, поэтому они пока не могут использовать самостоятельный wazap. Держите read-токен в клиентах, которым нужно только читать; выдавайте write-токен осознанно.

Настройки

Флаги важнее переменных окружения, а те важнее <data-dir>/.env.

Известные ограничения

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

• История — это то, что синхронизирует телефон. wazap видит ту историю, которую WhatsApp передаёт привязанному устройству, а не всю вашу переписку.

• @lid идентификаторы. WhatsApp адресует собеседников по приватному идентификатору, а не по номеру телефона. wazap переводит их обратно в номера телефонов, когда знает соответствие, и передаёт @lid как есть, когда не знает.

• Телефон должен оставаться доступным. Привязанное устройство перестаёт получать сообщения, если телефон был офлайн достаточно долго; get_status сообщает об этом.

• Токен одного устройства. Привязка привязана к одному устройству; повторный вход переносит сессию и разлогинивает предыдущую.

• @lid не везде. Некоторые поля адресуются по @lid, а не по номеру телефона; wazap преобразует их обратно в номера телефонов, когда узнаёт соответствие.

Разработка

npm install
npm run typecheck
npm test                       # builds, then runs node --test
node test/smoke-stdio.mjs      # drives the built binary over MCP stdio
npm run dev -- status          # run from source with tsx

npm test не требует подключённого телефона. Smoke-тест stdio запускает собранный бинарник с временным каталогом данных и проверяет, что инструменты перечисляются и get_status работает без привязки.

Лицензия MIT.