Skip to main content
Glama
WhatsApp MCP Server

WhatsApp MCP Server

by danialadzhar

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-local

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

Инструмент

Описание

whatsapp_status

Статус подключения + статистика БД

whatsapp_list_chats

Список чатов (отсортированный по последнему сообщению), поиск по ключевым словам

whatsapp_read_messages

Чтение сообщений из конкретного JID чата


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

  • 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

ОС

Путь

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

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


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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides Claude with read-only access to your WhatsApp chat history entirely on your local machine, enabling natural language search, summarization, and retrieval of messages without sending data to the cloud.
      14 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables Claude to read and search your WhatsApp chat history locally with no cloud or API keys, and optionally send audited messages.
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables Claude to read WhatsApp Desktop chats on a Mac, including messages, images, documents, and locally transcribed audio, through a local MCP server. Everything runs on the Mac with read-only access and no messages sent.
      6
      4
      MIT