VK Ads MCP All in One

<p align="center"> <img src="docs/img/cover.png" alt="VK Ads MCP: аналитика и управление рекламой" width="100%"> </p>

<h1 align="center">VK Ads MCP All in One</h1>

<p align="center"><strong>Бесплатный MCP-сервер для полноценной настройки, анализа и ведения рекламы во VK с помощью ИИ.</strong></p>

<p align="center"> <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-22%2B-339933?logo=nodedotjs&logoColor=white" alt="Node.js 22+"></a> <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-stdio-1f6feb" alt="MCP stdio"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0b8f60" alt="Лицензия MIT"></a> <img src="https://img.shields.io/badge/version-0.1.30-2563eb" alt="Версия 0.1.30"> </p>

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

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

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

[!IMPORTANT] Создание, изменение и удаление объектов, а также загрузка, отправка и экспорт данных выполняются только после вашего явного запроса. Перед изменением сервер проверяет действие и актуальное состояние кабинета через vk_ads_action_prepare; запись начинается только при ready: true.

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

[!TIP] Установка выполняется одной командой. Установщик скачает сервер, запросит данные VK Ads, подключит выбранные MCP-клиенты и установит навык для работы с VK Рекламой в каждый из них.

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

<table width="100%"> <thead> <tr> <th width="30%">Потребуется</th> <th width="70%">Условие</th> </tr> </thead> <tbody> <tr> <td>Node.js</td> <td><a href="https://nodejs.org/en/download">Установите Node.js версии 22 или новее по официальной инструкции</a>. npm устанавливается вместе с Node.js</td> </tr> <tr> <td>VK Реклама</td> <td>Откройте <a href="https://ads.vk.ru/hq/settings">настройки личного кабинета VK Рекламы</a>. Внизу страницы, в разделе «Получить API-доступ», выдаются <code>client_id</code> и <code>client_secret</code></td> </tr> </tbody> </table>

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

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

<details> <summary><strong>Что сделает установщик</strong></summary>

1. Скачает последнюю версию, установит зависимости и соберёт сервер.
2. Запросит client_id и client_secret. Секрет вводится в скрытом режиме.
3. Предложит подключить поиск сообществ через отдельный OAuth VK.
4. Сохранит учётные данные и токены в локальном auth.env.
5. Найдёт установленные MCP-клиенты и покажет список с галочками. Стрелки перемещают курсор, пробел снимает или ставит галочку, Enter подтверждает выбор.
6. Подключит сервер под именем vk-ads.
7. Установит навык для работы с VK Рекламой во все выбранные клиенты.

</details>

[!NOTE] Поддерживаются OpenCode, OpenClaw, Hermes Agent, Codex CLI, Claude Code, Gemini CLI, Qwen Code, Kimi Code CLI и Cursor. По умолчанию выбраны все найденные клиенты. Для продолжения нужен хотя бы один. Чтобы установить сервер без подключения к клиенту, используйте --no-register.

<details> <summary><strong>Что устанавливается вместе с MCP</strong></summary>

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

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

</details>

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

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

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

Обновление

[!TIP] Для обновления повторно выполните команду установки. Установщик покажет установленную и доступную версии.

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

<table width="100%"> <thead> <tr> <th width="30%">Действие</th> <th width="70%">Результат</th> </tr> </thead> <tbody> <tr> <td>Обновить</td> <td>Установщик снова покажет список найденных клиентов. Ранее настроенные клиенты будут отмечены, остальные можно выбрать дополнительно. <code>auth.env</code>, токены и локальный аудит сохранятся</td> </tr> <tr> <td>Установить заново</td> <td>Установщик снова предложит выбрать клиенты, запросит <code>client_id</code> и <code>client_secret</code>, а сохранённые токены будут удалены</td> </tr> </tbody> </table>

<details> <summary><strong>Каталоги установки</strong></summary>

<table width="100%"> <thead> <tr> <th width="30%">Система</th> <th width="70%">Каталог по умолчанию</th> </tr> </thead> <tbody> <tr> <td>macOS</td> <td><code>~/Library/Application Support/VK Ads MCP</code></td> </tr> <tr> <td>Linux</td> <td><code>~/.local/share/vk-ads-mcp</code></td> </tr> <tr> <td>Windows</td> <td><code>%LOCALAPPDATA%\VK Ads MCP</code></td> </tr> </tbody> </table>

</details>

<details> <summary><strong>Дополнительные параметры установки</strong></summary>

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

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

</details>

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

[!NOTE] Учётные данные и токены хранятся только в локальном auth.env внутри каталога установки. Токен с истекающим сроком действия обновляется автоматически.

<details> <summary><strong>Содержимое auth.env</strong></summary>

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

</details>

<details> <summary><strong>Получение и обновление токена VK Ads</strong></summary>

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

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

</details>

<details> <summary><strong>Токен для сообществ VK</strong></summary>

Инструменты сообществ используют отдельный 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 при запуске.

</details>

<details> <summary><strong>Хранение и защита данных</strong></summary>

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

</details>

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

<table width="100%"> <thead> <tr> <th width="25%">Раздел</th> <th width="75%">Возможности</th> </tr> </thead> <tbody> <tr> <td>Реклама</td> <td>Кампании, группы, объявления, массовые действия и перемодерация</td> </tr> <tr> <td>Креативы</td> <td>Загрузка изображений, видео и HTML5 ZIP</td> </tr> <tr> <td>Статистика</td> <td>Дневные, итоговые, быстрые, целевые, in-app и офлайн-метрики</td> </tr> <tr> <td>Аудитории</td> <td>Счётчики, цели, списки, сегменты, связи и ключи доступа</td> </tr> <tr> <td>Лиды и опросы</td> <td>Формы, логотипы, тестовые лиды, архивирование и приватный экспорт</td> </tr> <tr> <td>Данные</td> <td>Прайс-листы, подписки, локальная география, URL и справочники</td> </tr> <tr> <td>Кабинет</td> <td>Профиль, язык, приложения и безопасные статусы ОРД</td> </tr> <tr> <td>Сообщества VK</td> <td>Поиск, фильтрация, анализ публичных записей, скоринг, фоновые исследования, снимки и экспорт</td> </tr> </tbody> </table>

[!NOTE] Полный перечень инструментов, тип доступа и статусы приведены в каталоге инструментов.

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

[!IMPORTANT] Записывающие инструменты используют строгие входные схемы, проверяют актуальное состояние объекта и по возможности читают его повторно после изменения.

<details> <summary><strong>Как подтверждается изменение</strong></summary>

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

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

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

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

</details>

<details> <summary><strong>Пример подготовки и записи</strong></summary>

Для проверки изменения языка 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. Запись в этом случае не выполняется.

</details>

<details> <summary><strong>Что хранится в локальном журнале</strong></summary>

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

</details>

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

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

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

MCP-клиенты

[!NOTE] Установщик находит OpenCode, OpenClaw, Hermes Agent, Codex CLI, Claude Code, Gemini CLI, Qwen Code, Kimi Code CLI и Cursor, затем предлагает выбрать нужные клиенты.

<table width="100%"> <thead> <tr> <th width="30%">Клиент</th> <th width="70%">Инструкция</th> </tr> </thead> <tbody> <tr> <td>Codex</td> <td><a href="docs/setup-codex.md">Установка и проверка подключения</a></td> </tr> <tr> <td>OpenCode, OpenClaw, Hermes Agent, Claude Code, Gemini CLI, Qwen Code, Kimi Code CLI и Cursor</td> <td><a href="docs/setup-clients.md">Команды подключения и пути к конфигурациям</a></td> </tr> </tbody> </table>

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

<table width="100%"> <thead> <tr> <th width="40%">Документ</th> <th width="60%">Содержание</th> </tr> </thead> <tbody> <tr> <td><a href="docs/tools.md">Каталог инструментов</a></td> <td>Названия, назначение, тип доступа и статус каждого инструмента</td> </tr> <tr> <td><a href="docs/setup-codex.md">Подключение Codex</a></td> <td>Установка, запуск и проверка подключения</td> </tr> <tr> <td><a href="docs/setup-clients.md">Подключение MCP-клиентов</a></td> <td>Настройка OpenCode, OpenClaw, Hermes Agent, Claude Code, Gemini CLI, Qwen Code, Kimi Code CLI и Cursor</td> </tr> <tr> <td><a href="docs/SECURITY.md">Политика безопасности</a></td> <td>Хранение данных, токены и безопасность записывающих операций</td> </tr> <tr> <td><a href="docs/CHANGELOG.md">История изменений</a></td> <td>Пользовательские изменения по версиям</td> </tr> <tr> <td><a href="LICENSE">Лицензия MIT</a></td> <td>Условия использования и распространения</td> </tr> </tbody> </table>