VK Ads MCP All in One можно подключить к любому ИИ-агенту с поддержкой MCP. В диалоге с агентом можно анализировать эффективность рекламы, получать рекомендации по её улучшению, искать и создавать аудитории, загружать креативы, создавать кампании, группы и объявления и управлять ими на основе актуальных данных кабинета.

Сервер работает с официальным VK Ads API: читает кампании, группы и объявления, получает статистику, управляет аудиториями, креативами, лид-формами, опросами, подписками, прайс-листами и справочниками. Отдельный блок Core VK API ищет и анализирует публичные сообщества. Перед рекламным исследованием сервер требует описание покупателя и отдельное решение по конкурентам, затем разделяет целевые, смежные, партнёрские и конкурентные сообщества, а также сообщества поставщиков.

Инструкция по поиску и оценке сообществ показывает авторизацию, обязательный рекламный бриф, баллы, статусы и фактический пример детской футбольной секции в Домодедове. К примеру приложены отдельные рекомендации и ручная проверка, а также отчёт об отклонённых сообществах.

В текущей версии зарегистрировано 136 инструментов. Из них 122 прошли проверку реальными вызовами, ещё 14 пока недоступны или не проверены. Все 10 инструментов исследования сообществ VK и семь инструментов для аудиторий подписчиков доступны для обычной работы.

Быстрый старт

1. Подготовьте данные

2. Запустите установщик

npx --yes github:sergeylopukhov/vk-ads-mcp-all-in-one

1. Скачает последнюю версию, установит зависимости и соберёт сервер.

2. Запросит client_id и client_secret. Секрет вводится в скрытом режиме.

3. Предложит подключить поиск сообществ через отдельный OAuth VK.

4. Сохранит учётные данные и токены в локальном auth.env.

5. Найдёт установленные MCP-клиенты и покажет список с галочками. Стрелки перемещают курсор, пробел снимает или ставит галочку, Enter подтверждает выбор.

6. Подключит сервер под именем vk-ads.

7. Установит навык для работы с VK Рекламой во все выбранные клиенты.

Универсальный Agent Skill устанавливается для каждого выбранного клиента и автоматически включается в задачах о VK Ads и сообществах VK. Он выбирает подходящие инструменты MCP, помогает восстанавливать токены, проверять подключение, анализировать статистику и сообщества, управлять кампаниями, аудиториями, лидами и опросами. Навык запускает инструменты записи только после вашего явного запроса. Навык и его справочники обновляются вместе с сервером.

Если перед поиском сообществ нужно собрать подробный бриф, навык предлагает ответить в чате или установить отдельный интерактивный опросник. Опросник устанавливается только с вашего согласия. Его установщик поддерживает OpenCode, Claude Code, Codex, Cursor, Gemini CLI, Qwen Code, Kimi Code CLI, Hermes Agent и другие клиенты формата Agent Skills.

3. Проверьте подключение

Перезапустите выбранные клиенты и отправьте:

Проверь подключение к VK Рекламе и покажи доступные кампании. Ничего не меняй.

Обновление

npx --yes github:sergeylopukhov/vk-ads-mcp-all-in-one

Для другой папки или ветки:

npx --yes github:sergeylopukhov/vk-ads-mcp-all-in-one --install-dir "/полный/путь" --ref main

Для установки без интерактивного выбора:

npx --yes github:sergeylopukhov/vk-ads-mcp-all-in-one --clients codex,openclaw,hermes

Параметр --all-detected подключает все найденные клиенты, а --no-register пропускает их настройку.

Все параметры:

npx --yes github:sergeylopukhov/vk-ads-mcp-all-in-one --help

Как создаётся и хранится токен

VK_ADS_CLIENT_ID=
VK_ADS_CLIENT_SECRET=
VK_ADS_TOKEN=
VK_ADS_REFRESH_TOKEN=
VK_ADS_TOKEN_EXPIRES_AT=
VK_API_TOKEN=
VK_API_TOKEN_TYPE=vk_id
VK_API_CLIENT_ID=
VK_API_DEVICE_ID=
VK_API_REFRESH_TOKEN=
VK_API_TOKEN_EXPIRES_AT=
VK_COMMUNITY_RESEARCH_TTL_DAYS=30

Чтобы отключить автоматическое удаление результатов исследований, установите VK_COMMUNITY_RESEARCH_TTL_DAYS=0. В этом режиме сервер не использует сохранённый анализ как кэш: новые поиски получают актуальные данные VK.

При первом запросе сервер получает токен по client_id и client_secret. Если VK Ads возвращает refresh_token, сервер сохраняет его и заранее обновляет токен доступа.

Токен с истекающим сроком действия обновляется автоматически. После HTTP 401 сервер один раз обновляет отклонённую пару и повторяет запрос. Для ручного обновления используется vk_ads_oauth_token_refresh. Если пара полностью отозвана на другом компьютере и обновить её невозможно, vk_ads_oauth_current_tokens_delete удаляет все токены настроенного аккаунта, очищает локальные значения и запрашивает новую пару.

Инструменты сообществ используют отдельный VK_API_TOKEN. По умолчанию установщик предлагает режим OAuth legacy через встроенное приложение VK с client_id=6270012: достаточно нажать Enter. Для VK ID укажите своё приложение. Также можно сохранить VK_API_CLIENT_ID, VK_API_DEVICE_ID, VK_API_REFRESH_TOKEN и срок действия, чтобы сервер обновлял токен Core VK при запуске.

auth.env исключён из Git и npm-пакета. На macOS и Linux установщик создаёт его с правами 0600. Токены, client_secret и полные приватные ответы VK Ads не выводятся через MCP.

Что умеет сервер

Безопасность записи

Записывающие инструменты используют фиксированные API-маршруты и строгие входные схемы. vk_ads_action_prepare позволяет заранее проверить действие без изменений в кабинете. Он возвращает ready, списки недостающих и несовместимых условий, предупреждения, допустимые значения и безопасный requestDraft.

Если подготовка возвращает requiresConfirmation=true, вы увидите предложенное исправление suggestedPatch. Связанный объект изменится только после вашего отдельного согласия. При ready=true MCP-клиент выполнит одну подготовленную операцию с теми же данными.

Для операций над существующим объектом сервер читает актуальное состояние непосредственно перед записью. После изменения он повторно читает объект или коллекцию, когда VK Ads предоставляет подходящий контракт.

Успешный HTTP-ответ не считается доказательством изменения. Если контрольное чтение не подтвердило результат, MCP возвращает ошибку или неподтверждённый итог. Например, remoderated=false не превращается в успешную перемодерацию.

Для проверки изменения языка MCP-клиент сначала передаёт в vk_ads_action_prepare имя действия и его входные данные:

{
  "action": "user.language_update",
  "input": {
    "version": "v3",
    "language": "en"
  }
}

При ready=true MCP-клиент передаёт те же поля в vk_ads_user_language_update:

{
  "version": "v3",
  "language": "en"
}

Если английский язык уже установлен, подготовка вернёт ready=false, stage="compatibility" и код user_language_noop. Запись в этом случае не выполняется.

Журнал операций хранится локально в .vk-ads-audit.jsonl. В нём нет токенов, содержимого запросов, идентификаторов кампаний, названий или ответов VK Ads.

Диагностика ошибок VK

Если VK отклоняет запрос, MCP возвращает код ошибки, безопасное сообщение провайдера и пути к полям с ошибками. Например, вместо одного validation_failed будет указано поле content.image_1080x607 и причина отказа, если VK передал эти сведения.

Из диагностики удаляются токены, секреты, пароли, адреса страниц, электронная почта и исходные строки загруженных файлов. Сервер обрабатывает ошибки одинаково для инструментов VK Ads, авторизации, поиска сообществ и обновления токена VK ID.

MCP-клиенты

Документация