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 アプリにサーバーを追加します。手順は以下の5つのアプリ向けに記載しています。
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 広告のオブジェクトの仕組み

オブジェクトには3種類の異なる状態があります。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.