VK Реклама MCP

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

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

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

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

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

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

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

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

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

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

Codex

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

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

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

codex mcp add vk-ads -- npx -y mcp-vk-ads@latest

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

codex mcp list

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

Claude Code

claude mcp add \
  --transport stdio \
  --scope user \
  vk-ads \
  -- npx -y mcp-vk-ads@latest

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

claude mcp list

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

Claude Desktop

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

{
  "mcpServers": {
    "vk-ads": {
      "command": "npx",
      "args": ["-y", "mcp-vk-ads@latest"]
    }
  }
}

Если 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:

{
  "mcpServers": {
    "vk-ads": {
      "command": "npx",
      "args": ["-y", "mcp-vk-ads@latest"]
    }
  }
}

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

VS Code

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

{
  "servers": {
    "vk-ads": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-vk-ads@latest"]
    }
  }
}

Проверьте запуск командой 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 не повторяйте создание вслепую: операция могла успеть примениться, сначала проверьте список объектов.

Подключение кабинета

Скажите ассистенту:

Подключи ВК Рекламу

Он покажет, что сделать: в ads.vk.com открыть Настройки → Доступ к API, создать приложение и прислать в чат client_id и client_secret. Дальше сервер сам получит токен и проверит, в какой кабинет попал. Перезапускать AI-приложение и править его конфигурацию не нужно. Если раздел «Доступ к API» недоступен, запросите доступ у поддержки VK Рекламы.

Дальше подключение живёт само: токен VK действует около суток и продлевается автоматически по refresh_token. Проверить состояние — «покажи статус подключения», отключить — «отключи ВК Рекламу».

client_id и client_secret дают полный доступ к рекламному кабинету, включая трату бюджета. Сервер хранит их в ~/.config/mcp-vk-ads/credentials.json с правами только для владельца (0600) — client_secret нужен потому, что VK требует его при каждом продлении токена. Ни один инструмент их не возвращает.

Браузерного «войти и подтвердить» у VK Рекламы для сторонних серверов нет: сценарий authorization_code VK выдаёт только партнёрам с согласованным redirect_uri, поэтому подключение идёт через приложение самого пользователя. Кабинеты клиентов агентства требуют гранта agency_client_credentials — для них нужен готовый токен в VK_ADS_TOKEN (см. документацию VK Ads API).

Настройка

Настраивать нечего: всё нужное сервер спрашивает в диалоге. Переменные окружения пригодятся только для CI и автоматических установок, где диалога нет. Все они необязательные — сервер работает без единой из них.

Переменная	Назначение
`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`.

Как выпустить токен для VK_ADS_TOKEN вручную

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. Он живёт около суток и сам не продлевается: при invalid_token выпустите новый. У одного пользователя не больше 5 активных токенов на приложение; старые отзываются запросом POST /api/v2/oauth2/token/delete.json — он удаляет все токены этого пользователя для данного client_id.

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

Страницы и большие кабинеты. Одна страница списка содержит до 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.