askads/mcp-vk-ads

npm CI Glama License: MIT

VK Реклама MCP подключает AI-приложение к рекламному кабинету VK Ads. Можно спросить, какие кампании тратят бюджет без результата, сравнить группы и объявления, подготовить новую кампанию или изменить ставку. В отличие от ручного перехода по разделам кабинета, ассистент сопоставляет кампании, статистику, баланс и статусы в одном диалоге.

• 18 инструментов. Кампании, группы, объявления, статистика, баланс, лимиты API, регионы и универсальный запрос к API.
• Живая реклама. Ставки, бюджеты и расход отображаются в валюте рекламного кабинета — без пересчёта микроединиц.
• Полная иерархия. Кампания (ad_plan) → группа (ad_group) → объявление (banner).
• Сначала анализ. Списки, отчёты, баланс и статусы доступны только на чтение.
• Изменения — в боевом кабинете. Создание, обновление и действия со статусами применяются сразу; у VK Ads нет песочницы.

Начните с безопасного запроса:

Покажи кампании моего аккаунта VK Рекламы и расход за прошлую неделю по группам объявлений.

Подключить сервер · Посмотреть сценарии · Открыть техническую документацию

Увидеть работу за минуту

Содержание

• Быстрый старт
• Что можно поручить
• Как устроены объекты VK Рекламы
• Что может изменить данные
• Как получить токен
• Настройка
• Данные, лимиты и работа в фоне
• Техническая документация
• Поддержка

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

Нужны Node.js 20 или новее и access-токен VK Ads. Сервер запускается через npx, поэтому отдельно устанавливать пакет не требуется.

1. Получите токен и добавьте сервер в AI-приложение — инструкции для пяти приложений ниже.
2. Спросите: «Покажи кампании моего аккаунта VK Рекламы и расход за прошлую неделю по группам объявлений».

codex mcp add vk-ads \
  --env VK_ADS_TOKEN=ваш_токен \
  -- npx -y mcp-vk-ads@latest

codex mcp list

claude mcp add \
  --env VK_ADS_TOKEN=ваш_токен \
  --transport stdio \
  --scope user \
  vk-ads \
  -- npx -y mcp-vk-ads@latest

claude mcp list

{
  "mcpServers": {
    "vk-ads": {
      "command": "npx",
      "args": ["-y", "mcp-vk-ads@latest"],
      "env": {
        "VK_ADS_TOKEN": "ваш_токен"
      }
    }
  }
}

{
  "mcpServers": {
    "vk-ads": {
      "command": "npx",
      "args": ["-y", "mcp-vk-ads@latest"],
      "env": {
        "VK_ADS_TOKEN": "ваш_токен"
      }
    }
  }
}

{
  "servers": {
    "vk-ads": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-vk-ads@latest"],
      "env": {
        "VK_ADS_TOKEN": "${input:vk_ads_token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "vk_ads_token",
      "description": "Access-токен VK Ads",
      "password": true
    }
  ]
}

Что можно поручить

Разобраться с расходом и результатом

• «Покажи расход, показы, клики и CTR по кампаниям за последние 7 дней».
• «Какие объявления тратят больше всего и не приносят результата?»
• «Сравни группы объявлений внутри этой кампании по расходу и кликам».

Понять, почему реклама не показывается

• «Покажи статус, доставку и модерацию всех объявлений этой группы».
• «Какие кампании сейчас остановлены?»
• «Найди объявления, которые не прошли модерацию».

Подготовить изменения в рекламе

• «Создай текстовую кампанию с дневным бюджетом 5 000 рублей».
• «Измени дневной бюджет этой группы на 1 500 рублей».
• «Останови объявление 12345».

Такие команды меняют боевой кабинет. Перед вызовом убедитесь, что ассистент правильно определил кампанию, группу, объявление и сумму.

Найти данные для настройки

• «Покажи баланс и валюту моего кабинета».
• «Сколько запросов к API осталось?»
• «Найди ID региона Москва для таргетинга».

Как устроены объекты VK Рекламы

У объекта есть три разных состояния. status можно менять: active, blocked или deleted. delivery и moderation_status только объясняют, почему объект показывается или нет; напрямую их изменить нельзя.

Что может изменить данные

У типизированных инструментов создания, обновления и смены статуса нет внутреннего параметра confirmWrite. Как AI-приложение запрашивает подтверждение, зависит от его настроек. После сетевой ошибки или 5xx не повторяйте создание вслепую: операция могла успеть примениться, сначала проверьте список объектов.

Как получить токен

Токен выдаёт кабинет VK Ads:

1. В ads.vk.com откройте Настройки → Доступ к API и создайте приложение. Сохраните client_id и client_secret. Если раздел недоступен, запросите доступ к API у поддержки VK Ads.

2. Обменяйте их на access-токен кабинета:

   curl -X POST https://ads.vk.com/api/v2/oauth2/token.json \
     -d grant_type=client_credentials \
     -d client_id=ВАШ_CLIENT_ID \
     -d client_secret=ВАШ_CLIENT_SECRET
   

3. Возьмите access_token из ответа и сохраните его как VK_ADS_TOKEN.

Токен даёт доступ к рекламному кабинету, включая возможность тратить бюджет, и хранится в конфигурации MCP-клиента открытым текстом. Относитесь к нему как к паролю. Если API отвечает invalid_token, выпустите и укажите новый токен.

Для агентств, работающих с кабинетами клиентов, нужен сценарий authorization_code — см. документацию VK Ads API.

Настройка

Данные, лимиты и работа в фоне

• Страницы и большие кабинеты. Одна страница списка содержит до 250 объектов. При autoPaginate сервер возвращает не более 1 000 объектов и помечает неполный результат полем _truncated.
• Лимиты API. Инструмент get_throttling показывает текущий остаток лимитов. Проверяйте его перед массовыми операциями.
• Повторы запросов. Таймаут одного запроса — 60 секунд. Сервер делает до трёх повторов: для любого метода при 429, а для чтения ещё при сетевой ошибке, тайм-ауте и 5xx. Задержка учитывает Retry-After и не превышает 30 секунд.
• Нет фонового наблюдения. Сервер работает, когда его вызывает AI-приложение. Если приложение поддерживает задания по расписанию, в нём можно настроить периодический запрос статистики или статусов.
• Анонимная телеметрия. По умолчанию сервер отправляет случайный идентификатор установки, имя события или инструмента, версии сервера, Node.js, ОС и AI-клиента. В неё не попадают токен, данные кабинета, аргументы инструментов, ваши сообщения и значения переменных окружения. Отключить её для MCP-серверов Ask Ads: ASKADS_TELEMETRY=0.

Техническая документация

• Каталог MCP-возможностей — страницы по пользовательским задачам для каждого инструмента.
• Все инструменты и параметры
• Документация по разработке
• Пакет в npm
• Документация VK Ads API

Поддержка

Нашли ошибку или не хватает сценария? Создайте issue или напишите в Telegram.