MCP Whatsapp для Claude Desktop

Сервер Model Context Protocol (MCP), который предоставляет Claude Desktop доступ только для чтения к вашим чатам и истории сообщений WhatsApp.

Построен на базе Baileys (протокол WhatsApp Web) — без номера телефона, без бизнес-API, без облачных сервисов. Все работает локально на вашем компьютере.

⚠️ Отказ от ответственности Это неофициальная интеграция. WhatsApp может заблокировать аккаунты, использующие неавторизованные клиенты. Используйте дополнительный/тестовый номер, а не основной. Автор не несет ответственности за блокировки.

✨ Возможности

• 🔌 Локальная работа — без внешних API, без облака

• 💾 SQLite-хранилище — чаты и сообщения сохраняются в локальную БД

• 📚 Синхронизация истории — загружает существующую историю WhatsApp при первом сопряжении

• 🔎 Поиск чатов по имени, push-имени или JID

• 📖 Чтение сообщений из любого чата (текст, подписи к изображениям, метаданные медиа)

• 🧠 Нативная интеграция с Claude — общайтесь с Claude Desktop на обычном языке

Related MCP server: WhatsApp MCP Server

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

📦 Системные требования

• Node.js 18+ — проверьте командой node --version

• Claude Desktop (macOS или Windows) — скачать

• Аккаунт WhatsApp с телефоном, с которого можно отсканировать QR-код

• Рекомендуется macOS или Linux (Windows работает при настройке путей)

🚀 Установка

1. Клонируйте репозиторий

git clone https://github.com/danialadzhar/mcp-whatsapp.git
cd mcp-whatsapp

2. Установите зависимости

npm install

Если better-sqlite3 не собирается, убедитесь, что у вас установлены Xcode Command Line Tools (для macOS): xcode-select --install

🔐 Первая настройка (Сопряжение WhatsApp + Синхронизация истории)

⚠️ Важно — сделайте это ДО настройки Claude Desktop. QR-код можно отобразить в терминале только через setup.js. MCP-сервер (запускаемый Claude Desktop) не может показать QR-код, так как его стандартный вывод зарезервирован для протокола MCP. Если вы пропустите этот шаг и сразу перейдете к настройке Claude Desktop, ваш бот навсегда зависнет в состоянии connecting без возможности сопряжения.

1. Запустите скрипт настройки

node setup.js

В терминале появится QR-код.

2. Откройте WhatsApp на телефоне

• Перейдите в Настройки → Связанные устройства → Привязка устройства

• Когда появится запрос "Включить историю чатов" или аналогичный — выберите ДА, чтобы загрузить историю

• Отсканируйте QR-код из терминала

3. Дождитесь загрузки истории

Терминал выведет:

[HISTORY] chats=35 msgs=500 isLatest=false | batch #1 | DB: 35 chats, 500 messages
[HISTORY] chats=0 msgs=1200 isLatest=false | batch #2 | DB: 35 chats, 1700 messages
...

В зависимости от размера вашего аккаунта это займет 5-30 минут. Скрипт автоматически определяет завершение, когда в течение 30 секунд не поступает новых данных.

4. Остановите скрипт

Когда увидите HISTORY SYNC COMPLETE и SAFE TO EXIT, нажмите Ctrl+C.

⚙️ Настройка Claude Desktop

⚠️ Несовместимо с функциями Claude Desktop Cowork / Scheduled Tasks. Когда включены функции Cowork или Scheduled Tasks, Claude Desktop запускает несколько экземпляров MCP-сервера для фоновых агентов. WhatsApp разрешает только одно активное подключение связанного устройства, поэтому дублирующие экземпляры конфликтуют за сессию и вызывают цикл status=440, reconnect=true. Отключите обе функции в конфигурации (см. шаг 2 ниже), иначе интеграция не будет работать стабильно.

1. Найдите файл конфигурации Claude Desktop

2. Добавьте MCP-сервер

Откройте файл и добавьте этот блок в секцию mcpServers (создайте ключ, если его нет):

{
  "mcpServers": {
    "whatsapp": {
      "command": "/absolute/path/to/node",
      "args": [
        "/absolute/path/to/mcp-whatsapp/mcp-server.js"
      ]
    }
  }
}

Замените на ваши реальные пути:

• Узнать путь к node: which node (macOS/Linux) или where node (Windows)

• Используйте абсолютные пути — Claude Desktop не всегда корректно разрешает пути в оболочке

Пример (macOS, Homebrew node) с отключенными Cowork/Scheduled Tasks:

{
  "mcpServers": {
    "whatsapp": {
      "command": "/opt/homebrew/bin/node",
      "args": [
        "/Users/yourname/projects/mcp-whatsapp/mcp-server.js"
      ]
    }
  },
  "preferences": {
    "coworkScheduledTasksEnabled": false,
    "ccdScheduledTasksEnabled": false
  }
}

Если у вас уже есть блок "preferences" в конфигурации, просто добавьте в него два ключа *ScheduledTasksEnabled — не дублируйте блок.

3. Перезапустите Claude Desktop

Полностью завершите работу через Cmd+Q (не просто закройте окно), затем откройте снова.

4. Проверка

В любом чате Claude Desktop спросите:

what is my whatsapp status

Claude вызовет инструмент whatsapp_status. Подтвердите запрос на разрешение, когда он появится.

💬 Примеры запросов

После подключения вы можете спрашивать Claude Desktop:

• "Список моих 10 последних чатов WhatsApp"

• "Найди в WhatsApp чаты с 'Ахмадом'"

• "Сделай краткую сводку моих последних 50 сообщений с 60123456789@s.whatsapp.net"

• "Сколько у меня непрочитанных чатов в WhatsApp?"

• "Покажи последнее сообщение из каждого группового чата"

• "Найди переписки, где кто-то упоминал 'встречу'" (Claude объединит список + чтение)

Claude сам решает, какие инструменты вызывать, основываясь на вашем вопросе.

🐛 Устранение неполадок

❌ Error: Cannot find module '@whiskeysockets/baileys'

Вы не установили зависимости.

cd mcp-whatsapp
npm install

❌ Цикл status=440, reconnect=true в логах

Два процесса конфликтуют за одну сессию WhatsApp. Распространенные причины:

1. Claude Desktop запускает дубликаты MCP-серверов — отключите Cowork/Scheduled Tasks в claude_desktop_config.json:

   "preferences": {
     "coworkScheduledTasksEnabled": false,
     "ccdScheduledTasksEnabled": false
   }

2. Одновременно запущены скрипт в терминале и Claude Desktop — завершите процессы в терминале:

   ps aux | grep "mcp-whatsapp" | grep -v grep
   kill <PID>

3. Два экземпляра Claude Desktop — полностью завершите работу через Cmd+Q, откройте один раз.

❌ QR-код не появляется при запуске setup.js

• Убедитесь, что никакой другой процесс Node не удерживает auth_info/:

  ps aux | grep "mcp-whatsapp" | grep -v grep

• Полностью завершите Claude Desktop (Cmd+Q) перед запуском setup.js.

• Удалите auth_info/ и попробуйте снова:

  rm -rf auth_info
  node setup.js

❌ Инструменты не появляются в Claude Desktop

1. Проверьте валидность JSON конфигурации:

   # macOS
   python3 -c "import json; json.load(open('$HOME/Library/Application Support/Claude/claude_desktop_config.json'))"

2. Проверьте логи MCP-сервера:

   # macOS
   tail -50 ~/Library/Logs/Claude/mcp-server-whatsapp.log

3. Проверьте правильность пути к node в конфигурации:

   which node

4. Полностью завершите и перезапустите Claude Desktop — перезагрузка конфигурации требует полного перезапуска приложения.

❌ connectionState: "connecting" бесконечно

• Сессия может быть повреждена. Исправьте повторным сопряжением:

  # 1. Quit Claude Desktop (Cmd+Q)
  # 2. Delete auth
  rm -rf auth_info whatsapp.db
  # 3. Re-run setup
  node setup.js
  # 4. Scan QR

❌ 0 chats, 0 messages в БД после настройки

• Вероятно, вы пропустили запрос "Включить историю чатов" в WhatsApp при сканировании QR-кода.

• WhatsApp предлагает синхронизацию истории только при начальном сопряжении. Исправление:

  rm -rf auth_info whatsapp.db
  node setup.js

  Когда телефон спросит, выберите включение истории в этот раз.

❌ Синхронизация истории не начинается даже с правильной конфигурацией

• Некоторые версии WhatsApp пропускают запрос на передачу истории. Обходные пути:

  • Обновите WhatsApp на телефоне до последней версии

  • На телефоне: Настройки → Чаты → Перенос истории чатов (если доступно)

  • Примите тот факт, что будут захватываться только новые сообщения

❌ Ошибки сборки node-gyp / better-sqlite3

• macOS: xcode-select --install

• Linux: sudo apt install build-essential python3

• Windows: установите windows-build-tools или Visual Studio Build Tools

❌ Отказано в доступе, когда Claude Desktop пытается вызвать инструмент

При первом вызове каждого инструмента Claude Desktop запрашивает одобрение. Выберите "Allow for this task" для удобства. Вы также можете настроить разрешения для каждого инструмента в настройках Claude Desktop.

❓ Часто задаваемые вопросы

Бот захватывает сообщения 24/7?

Нет. MCP-сервер работает только пока открыт Claude Desktop. Когда Claude Desktop закрывается, бот отключается.

Однако WhatsApp ставит в очередь недоставленные сообщения для связанных устройств на срок до ~14 дней. Когда вы снова откроете Claude Desktop, офлайн-сообщения придут и сохранятся в БД.

Для полноценного захвата 24/7 запустите отдельный фоновый демон (не входит в этот репозиторий).

WhatsApp заблокирует мой аккаунт?

Риск существует для любого неофициального клиента. Смягчение рисков:

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

• Не рассылайте спам (этот репозиторий работает только на чтение, поэтому риск ниже)

• Не используйте для массового маркетинга

Могу ли я отправлять сообщения через этот MCP?

Эта версия намеренно только для чтения (безопаснее). Чтобы добавить возможность отправки, добавьте инструмент whatsapp_send_message в mcp-server.js — но будьте осторожны, отправка через MCP — мощная функция, которой можно злоупотребить через инъекции промптов.

Где хранятся мои данные?

• auth_info/ — учетные данные сессии (храните в секрете, не делитесь и не коммитьте)

• whatsapp.db — SQLite с вашими чатами и сообщениями (храните в секрете)

Оба файла добавлены в gitignore.

Как удалить?

# Quit Claude Desktop
# Remove MCP server entry from claude_desktop_config.json
# Delete the repo folder
rm -rf mcp-whatsapp

На телефоне: WhatsApp → Связанные устройства → удалите это устройство.

Могут ли несколько MCP-серверов использовать одну сессию WhatsApp?

Нет. WhatsApp разрешает только одно активное подключение на авторизацию связанного устройства. Запуск нескольких экземпляров MCP вызывает конфликтный цикл status=440.

Как насчет групп?

Групповые чаты поддерживаются — отображаются и читаются как любые другие чаты. JID заканчиваются на @g.us.

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

• Несовместимо с Claude Desktop Cowork / Scheduled Tasks — эти функции запускают дублирующие экземпляры MCP, которые разрывают единственное соединение WhatsApp. Должны быть отключены (см. Настройка Claude Desktop).

• Работает только пока открыт Claude Desktop — для захвата 24/7 нужен отдельный демон (не включен).

• Медиа (изображения, видео, аудио) не загружаются — только текст + метаданные.

• Реакции отслеживаются как отдельные сообщения, не привязываются к родительским.

• Удаленные сообщения не захватываются.

• Объем синхронизации истории зависит от WhatsApp — обычно последние 6 месяцев.

• Протестировано на macOS/Linux; пути Windows требуют корректировки в конфигурации.

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

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

Проблемы и PR приветствуются. Пожалуйста:

• Оформляйте тикеты с логами (удаляйте личные данные)

• Ограничивайте PR одной функцией/исправлением

• Не добавляйте send_message без продуманного дизайна безопасности (шлюзы разрешений, лимиты скорости, UX подтверждения)

📄 Лицензия

MIT © Danial Adzhar

🙏 Благодарности

• Baileys — реверс-инжиниринг клиента WhatsApp Web

• Model Context Protocol — стандарт от Anthropic

• better-sqlite3 — быстрый синхронный SQLite