Большинство туториалов по WhatsApp MCP останавливаются на Claude Desktop. Это руководство от Whapi.Cloud написано для разработчиков, использующих Cursor, VS Code и GitHub Copilot — с готовыми JSON-конфигами и рабочим шагом проверки для каждого.
Раньше автоматизация WhatsApp требовала кастомного кода — REST-клиентов, обработчиков webhook, управления сессиями и логики обновления токенов. whapi-mcp заменяет всё это командой на естественном языке вашему AI-агенту. Установите MCP-сервер один раз, вставьте JSON-конфиг — и полная библиотека инструментов WhatsApp будет доступна любому совместимому с MCP клиенту, который вы уже используете.
Что такое MCP на самом деле
MCP — Model Context Protocol — это система плагинов для AI-агентов, позволяющая вызывать реальные внешние инструменты. Один интерфейс, множество совместимых клиентов: запустите один MCP-сервер — и каждый подключённый агент сможет использовать его инструменты без отдельных интеграций для каждого клиента.
Без MCP ваш агент может только предлагать действия. С MCP — он их выполняет: вызывает API, читает переписку, отправляет ответ, подтверждает доставку. Разрыв между предложением и автоматизацией — это доступ к инструментам.
Что даёт whapi-mcp
whapi-mcp — это MCP-сервер, созданный Whapi.Cloud, который оборачивает REST API Whapi и предоставляет его как структурированные инструменты любому MCP-совместимому AI-агенту. Автоматически сгенерированные из OpenAPI-спецификации Whapi, инструменты охватывают сообщения, группы, каналы, контакты, медиа, метки и многое другое — 165 инструментов в общей сложности.
Работает в Cursor, VS Code Agent Mode, GitHub Copilot Chat, Windsurf и Claude Desktop. Все пять клиентов используют один npm-пакет @whapi-cloud/whapi-mcp. Различается только путь к файлу конфигурации.
В отличие от QR-мостов, whapi-mcp подключается через производственную инфраструктуру Whapi — никаких локальных файлов сессий, повторных сканирований после обрывов сети, ночных переподключений. Стабильность управляется в облаке, а не на вашей машине разработчика.
| Функция | whapi-mcp (Whapi.Cloud) | QR-мост (локальная сессия) |
|---|---|---|
| Стабильность сессии | Производственная стабильность, управляется в облаке | Обрывается при сетевых сбоях; требует повторного QR-сканирования |
| Время настройки | Менее 10 минут (одна команда npx) | 30 -- 60 мин (локальный сервер + QR-сканирование + настройка портов) |
| Поддержка нескольких номеров | Да — несколько каналов на аккаунт | Обычно один номер на экземпляр сервера |
| Покрытие инструментов MCP | 165 структурированных инструментов из OpenAPI-спецификации | Варьируется; часто требует кастомных обёрток |
| API групп и каналов | Полный доступ | Частичный или ненадёжный |
Перед Началом
Проверьте эти требования перед запуском любой команды установки:
-
Node.js 18 или выше — необходим для запуска
npx. Проверьте командойnode -vв терминале. -
API-токен Whapi — зарегистрируйтесь на whapi.cloud, подключите номер WhatsApp и скопируйте токен из настроек канала в панели Whapi.
-
IDE с поддержкой MCP — Cursor (любая актуальная версия), VS Code с включённым Agent Mode, или GitHub Copilot Chat в VS Code 1.99+ с подходящим планом Copilot.
Подключите WhatsApp MCP за 10 Минут
Cursor, VS Code и GitHub Copilot используют один пакет @whapi-cloud/whapi-mcp — различается только путь к файлу конфигурации. Установите пакет один раз через npx; настройте по одному разу для каждого IDE.
Шаг 1 — Запустите сервер один раз для проверки
Перед настройкой любого IDE выполните это в терминале, чтобы убедиться, что пакет доступен и токен валиден:
npx -y @whapi-cloud/whapi-mcp --api-token YOUR_WHAPI_TOKENЗамените YOUR_WHAPI_TOKEN на ваш реальный токен. Если MCP-сервер запустился без ошибок — токен работает. Глобальная установка npm не нужна; конфиг IDE запускает npx автоматически при старте.
Шаг 2 — Настройте ваш IDE
Каждый IDE читает конфигурацию MCP-сервера из определённого JSON-файла. Внутренняя структура практически одинакова для всех трёх клиентов — различаются только внешний ключ и расположение файла.
Cursor
Создайте или отредактируйте ~/.cursor/mcp.json для глобальной конфигурации (применяется ко всем проектам) или .cursor/mcp.json в корне проекта для конфигурации на уровне проекта:
{
"mcpServers": {
"whapi": {
"command": "npx",
"args": ["-y", "@whapi-cloud/whapi-mcp", "--api-token", "YOUR_WHAPI_TOKEN"]
}
}
}Сохраните, перезапустите Cursor и откройте панель агента — инструменты whapi появятся в списке доступных инструментов.
VS Code (Agent Mode)
Создайте .vscode/mcp.json в корне workspace. VS Code Agent Mode читает этот файл автоматически. Обратите внимание на ключ "type": "stdio" — он обязателен по схеме конфигурации MCP для VS Code:
{
"servers": {
"whapi": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@whapi-cloud/whapi-mcp", "--api-token", "YOUR_WHAPI_TOKEN"]
}
}
}Включите Agent Mode в настройках VS Code, если он ещё не активен. Сервер whapi запустится при открытии панели агента.
GitHub Copilot (VS Code)
Для GitHub Copilot Chat в VS Code добавьте запись MCP в settings.json на уровне пользователя или создайте .github/copilot/mcp.json в корне проекта. Поддержка MCP требует VS Code 1.99+ и подходящего плана Copilot:
{
"mcpServers": {
"whapi": {
"command": "npx",
"args": ["-y", "@whapi-cloud/whapi-mcp", "--api-token", "YOUR_WHAPI_TOKEN"]
}
}
}После сохранения откройте Copilot Chat в режиме Agent — инструменты whapi появятся в выборе инструментов.
Claude Desktop
Если вы также используете Claude Desktop, конфигурация помещается в claude_desktop_config.json. Структура идентична конфигу для Cursor:
{
"mcpServers": {
"whapi": {
"command": "npx",
"args": ["-y", "@whapi-cloud/whapi-mcp", "--api-token", "YOUR_WHAPI_TOKEN"]
}
}
}Шаг 3 — Защитите ваш токен
Никогда не вставляйте API-токен Whapi в файл конфигурации, который вы фиксируете в системе контроля версий. Вместо этого ссылайтесь на переменную окружения — большинство MCP-клиентов поддерживают ключ "env" в конфигурации сервера:
{
"mcpServers": {
"whapi": {
"command": "npx",
"args": ["-y", "@whapi-cloud/whapi-mcp", "--api-token", "${WHAPI_TOKEN}"]
}
}
}Установите WHAPI_TOKEN в переменных окружения системы или в файле .env, исключённом из git. Добавьте файл конфигурации в .gitignore, если он содержит сырой токен. Полные примеры — в руководстве по настройке Whapi MCP.
Проверьте Подключение
После перезапуска IDE откройте AI-агента и выполните:
List my WhatsApp chatsРабочее подключение вернёт ваши последние чаты с их Chat ID. Если они появились — настройка завершена. Ваш AI-агент теперь имеет прямой доступ к WhatsApp.
Ошибки MCP-сервера почти всегда сводятся к двум причинам: неверный путь к файлу конфигурации или лишние запятые в JSON. Оба случая вызывают молчаливые сбои парсинга.
Что можно делать — 6 реальных сценариев
Подключите MCP один раз — ваш AI-агент будет отправлять сообщения, управлять группами и читать чаты по простой команде на естественном языке. Шесть операций, которые работают сразу после настройки:
-
«Отправь сообщение Ивану, что его заказ готов» — агент вызывает
sendMessageTextс Chat ID Ивана и текстом сообщения. -
«Создай группу WhatsApp Sprint Team и добавь эти 5 номеров» — вызывает
createGroupдля создания группы, затемaddGroupParticipantс массивом участников. -
«Прочитай последние 20 сообщений из чата поддержки» — вызывает
getMessagesс chat ID и количеством. Возвращает полную переписку. -
«Отправь invoice.pdf клиенту в WhatsApp» — вызывает
sendMessageDocumentс ссылкой на файл и Chat ID получателя. -
«Покажи все непрочитанные чаты и сделай краткое резюме тем» — вызывает
getChatsдля списка чатов, затемgetMessagesпо каждому — AI извлекает и суммирует контекст. -
«Опубликуй обновление продукта в нашем канале WhatsApp» — вызывает
sendMessageTextс Chat ID каналаCHANNELID@newsletterв качестве получателя.
Каждый промпт соответствует одному вызову инструмента. Агент выбирает инструмент, заполняет параметры и возвращает результат — никакого кода интеграции писать или поддерживать не нужно.
Whapi Agent Skill — Устраните ошибки формата
AI-агенты галлюцинируют Chat ID WhatsApp. Без явных знаний о формате модель изобретает структурно неверные идентификаторы — и вызов инструмента завершается ошибкой, даже если агент выбрал правильный инструмент.
WhatsApp использует три различных формата Chat ID, которые необходимо использовать точно:
-
[email protected]— личные контакты (например,[email protected]) -
[email protected]— групповые чаты (например,[email protected]) -
CHANNELID@newsletter— Каналы WhatsApp (например,120363123456789012@newsletter)
Whapi Agent Skill — это загружаемый файл знаний для Cursor и VS Code. Установите его один раз — агент будет загружать правила форматирования Chat ID и паттерны использования инструментов в контекст перед каждой сессией. Процент успеха с первой попытки растёт; отладка Chat ID падает практически до нуля.
Инструкции по установке — в руководстве Whapi Agent Skills. Используйте whapi-mcp и Agent Skill вместе — они созданы друг для друга.
Быстрое Устранение Неполадок
Три проблемы, из-за которых большинство настроек заканчиваются неудачей:
-
MCP-сервер не найден после перезапуска IDE — файл конфигурации находится по неверному пути или содержит синтаксическую ошибку JSON. Глобальный конфиг Cursor:
~/.cursor/mcp.json. VS Code читает.vscode/mcp.jsonиз корня workspace. Проверьте JSON линтером — лишние запятые вызывают молчаливые сбои парсинга. -
Ошибка аутентификации или ответ 401 — API-токен недействителен, истёк или вставлен с лишними пробелами. Скопируйте его заново непосредственно из настроек канала в панели Whapi и замените значение в конфиге.
-
npx не может разрешить пакет — убедитесь, что Node.js 18+ установлен (
node -v). В корпоративных сетях или при VPN проверьте, что доступ к реестру npm не заблокирован. Попробуйтеnpm install -g @whapi-cloud/whapi-mcpв качестве запасного варианта и обновите конфиг, указав"command": "whapi-mcp".
Для редких случаев и дополнительных паттернов конфигурации смотрите руководство по настройке Whapi MCP. Исходный код и открытые issues — на GitHub (Whapi-Cloud/whapi-mcp).
Получите API-токен и выполните первую команду WhatsApp-агента менее чем за 10 минут. Если вы столкнётесь с нестандартным случаем, не описанным здесь, — откройте чат поддержки на этой странице. Команда Whapi отвечает быстро.
