VK Реклама MCP

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

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

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

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

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

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

Демонстрация: ассистент сопоставляет кампании, статистику и баланс VK Рекламы

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

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

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

Codex

Через интерфейс приложения:

Откройте Settings → Plugins → MCP servers.
Нажмите Add server.
Добавьте команду запуска npx -y mcp-vk-ads@latest и переменную окружения VK_ADS_TOKEN со своим токеном.

Через командную строку:

bash

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

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

bash

codex mcp list

Официальная инструкция Codex

Claude Code

Terminal

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

Проверьте сервер:

Terminal

claude mcp list

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

Claude Desktop

Откройте Settings → Developer → Edit Config и добавьте сервер в claude_desktop_config.json:

config.json

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

Если Edit Config недоступна, отредактируйте ~/Library/Application Support/Claude/claude_desktop_config.json на macOS или %APPDATA%\Claude\claude_desktop_config.json на Windows.

Cursor

Для всех проектов создайте ~/.cursor/mcp.json; только для текущего проекта — .cursor/mcp.json:

config.json

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

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

VS Code

Откройте палитру команд и выполните MCP: Open User Configuration. Добавьте в mcp.json:

config.json

{
  "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
    }
  ]
}

Проверьте запуск командой MCP: List Servers.

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

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

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

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

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

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

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

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

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

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

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

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

Объект	Роль
Кампания (`ad_plan`)	Верхний уровень: название, бюджет, ставка и период работы.
Группа (`ad_group`)	Настройки аудитории и размещения, собственные бюджет и ставка.
Объявление (`banner`)	Тексты, ссылки и креатив внутри группы.
Статистика	Отчёт по кампаниям, группам или объявлениям за период.

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

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

Действие	Что происходит
Списки, статистика, баланс, лимиты и регионы	Только чтение.
Создание и обновление кампаний, групп и объявлений	Сразу создаёт или меняет объект в боевом рекламном кабинете.
Действие со статусом	Активирует, останавливает или удаляет объект в живом кабинете.
`raw_request`	`GET` читает данные; `POST` и `DELETE` меняют их и требуют `confirmWrite=true`.

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

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

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

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

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

Terminal

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

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

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

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

Настройка

Переменная	Назначение
`VK_ADS_TOKEN`	Обязательный OAuth2 access-токен VK Ads.
`VK_ADS_LANG`	Язык ответов API; по умолчанию `ru`.
`VK_ADS_TIMEOUT_MS`	Таймаут одного запроса; по умолчанию 60 000 мс.
`VK_ADS_MAX_RETRIES`	Число повторов при временных ошибках; по умолчанию 3.
`VK_ADS_API_BASE`	Базовый адрес API; по умолчанию `https://ads.vk.com/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.