WhatsApp MCP Server

Это MCP-сервер (Model Context Protocol) для WhatsApp.

С его помощью можно искать и читать личные сообщения WhatsApp (включая изображения, видео, документы и голосовые сообщения), искать контакты и отправлять сообщения как отдельным пользователям, так и группам. Также поддерживается отправка медиафайлов: изображений, видео, документов и аудиосообщений.

Сервер подключается к личному аккаунту WhatsApp напрямую через WhatsApp Web multidevice API (с использованием библиотеки whatsmeow). Все сообщения хранятся локально в базе данных SQLite и передаются в LLM (например, Claude) только тогда, когда агент обращается к ним через инструменты (которые вы контролируете).

Ниже пример того, что можно сделать при подключении к Claude.

WhatsApp MCP

Чтобы получать обновления об этом и других проектах, оставьте email здесь

Внимание: как и многие MCP-серверы, WhatsApp MCP подвержен «летальной триаде». Это означает, что prompt injection может привести к утечке приватных данных.

Установка

Требования

Go
Python 3.6+
Приложение Anthropic Claude Desktop (или Cursor)
UV (менеджер пакетов Python), установка: curl -LsSf https://astral.sh/uv/install.sh | sh
FFmpeg (опционально) — требуется только для аудиосообщений. Чтобы отправлять аудиофайлы как воспроизводимые голосовые сообщения WhatsApp, они должны быть в формате .ogg Opus. При наличии FFmpeg MCP-сервер автоматически конвертирует аудиофайлы других форматов. Без FFmpeg можно по-прежнему отправлять сырые аудиофайлы через инструмент send_file.

Шаги

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

bash

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

Запустите WhatsApp-мост

Перейдите в директорию whatsapp-bridge и запустите Go-приложение:
bash
```
cd whatsapp-bridge
go run main.go
```
При первом запуске будет предложено отсканировать QR-код. Отсканируйте его мобильным приложением WhatsApp для аутентификации.

Примерно через 20 дней может потребоваться повторная аутентификация.
Подключитесь к MCP-серверу

Скопируйте приведённый ниже JSON, подставив актуальные значения {{PATH}}:
json
```
{
  "mcpServers": {
    "whatsapp": {
      "command": "{{PATH_TO_UV}}", // Выполните `which uv` и вставьте результат сюда
      "args": [
        "--directory",
        "{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server", // Перейдите в репозиторий, выполните `pwd` и вставьте результат сюда + "/whatsapp-mcp-server"
        "run",
        "main.py"
      ]
    }
  }
}
```
Для Claude сохраните файл как claude_desktop_config.json в директории конфигурации Claude Desktop:
~/Library/Application Support/Claude/claude_desktop_config.json
Для Cursor сохраните файл как mcp.json в директории конфигурации Cursor:
~/.cursor/mcp.json
Перезапустите Claude Desktop / Cursor

Откройте Claude Desktop — WhatsApp должен появиться как доступная интеграция.

Либо перезапустите Cursor.

Совместимость с Windows

При запуске проекта на Windows учтите, что go-sqlite3 требует включённого CGO для корректной компиляции и работы. По умолчанию CGO отключён на Windows, поэтому его необходимо явно включить и установить C-компилятор.

Шаги для настройки:

Установите C-компилятор Рекомендуется использовать MSYS2 для установки C-компилятора на Windows. После установки MSYS2 добавьте папку ucrt64\bin в переменную окружения PATH. → Пошаговое руководство доступно здесь.
Включите CGO и запустите приложение
bash
```
cd whatsapp-bridge
go env -w CGO_ENABLED=1
go run main.go
```

Без этой настройки вы, скорее всего, столкнётесь с ошибкой вида:

Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work.

Архитектура

Приложение состоит из двух основных компонентов:

Go WhatsApp Bridge (whatsapp-bridge/): Go-приложение, которое подключается к WhatsApp Web API, выполняет аутентификацию через QR-код и сохраняет историю сообщений в SQLite. Служит мостом между WhatsApp и MCP-сервером.
Python MCP Server (whatsapp-mcp-server/): Python-сервер, реализующий Model Context Protocol (MCP) и предоставляющий стандартизированные инструменты для взаимодействия Claude с данными WhatsApp — отправки и получения сообщений.

Хранение данных

Вся история сообщений хранится в базе данных SQLite в директории whatsapp-bridge/store/
База данных содержит таблицы для чатов и сообщений
Сообщения индексируются для эффективного поиска и извлечения

Использование

После подключения вы можете взаимодействовать с контактами WhatsApp через Claude, используя возможности AI в своих переписках.

MCP-инструменты

Claude имеет доступ к следующим инструментам для работы с WhatsApp:

search_contacts — поиск контактов по имени или номеру телефона
list_messages — получение сообщений с опциональными фильтрами и контекстом
list_chats — список доступных чатов с метаданными
get_chat — информация о конкретном чате
get_direct_chat_by_contact — поиск личного чата с конкретным контактом
get_contact_chats — список всех чатов с участием конкретного контакта
get_last_interaction — последнее сообщение с контактом
get_message_context — контекст вокруг конкретного сообщения
send_message — отправка сообщения WhatsApp на указанный номер телефона или group JID
send_file — отправка файла (изображение, видео, сырое аудио, документ) указанному получателю
send_audio_message — отправка аудиофайла как голосового сообщения WhatsApp (файл должен быть в формате .ogg Opus, либо должен быть установлен FFmpeg)
download_media — загрузка медиафайла из сообщения WhatsApp