VK Ads MCP

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 启动，因此无需单独安装软件包；安装时无需令牌。

1. 将服务添加到 AI 应用中——下方提供了五款应用的操作说明。
2. 说：“连接 VK 广告”——服务会在对话中引导你完成连接。
3. 询问：“显示我的 VK 广告账户中的广告系列，以及上周各广告组的支出。”

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

codex mcp list

claude mcp add \
  --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"]
    }
  }
}

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

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

可以交办哪些任务

了解支出和效果

• “显示过去 7 天各广告系列的支出、展示量、点击量和 CTR。”
• “哪些广告支出最多却没有效果？”
• “比较此广告系列中各广告组的支出和点击量。”

了解广告为何没有展示

• “显示此广告组所有广告的状态、投放情况和审核状态。”
• “目前有哪些广告系列已暂停？”
• “找出未通过审核的广告。”

准备广告调整

• “创建一个每日预算为 5 000 卢布的文字广告系列。”
• “将此广告组的每日预算改为 1 500 卢布。”
• “暂停广告 12345。”

此类命令会修改线上广告账户。调用前，请确认助手正确识别了广告系列、广告组、广告和金额。

查找设置所需的数据

• “显示我的广告账户余额和货币。”
• “还剩多少次 API 请求？”
• “查找用于定向投放的莫斯科地区 ID。”

VK 广告对象的结构

对象有三种不同的状态。status 可以修改：active、blocked 或 deleted。delivery 和 moderation_status 仅用于说明对象为何正在展示或未展示；无法直接修改它们。

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

У типизированных инструментов создания, обновления и смены статуса нет внутреннего параметра 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 и автоматических установок, где диалога нет. Все они необязательные — сервер работает без единой из них.

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

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

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