VK Ads MCP

Показывает, подключена ли VK Реклама: есть ли токен, откуда он взят (переменная окружения VK_ADS_TOKEN или сохранённый вход), когда истекает, какой client_id и аккаунт за ним стоят и где лежит файл с сохранёнными данными. Ничего не отправляет в сеть, не показывает ни токен, ни client_secret. Вызовите это, если инструменты VK Рекламы отвечают, что подключение не настроено.

Takes no parameters.

Первый шаг подключения VK Рекламы без правки конфигурации и без перезапуска клиента. Ничего не отправляет в сеть — возвращает инструкцию, которую нужно показать пользователю целиком: где в кабинете создать приложение и откуда скопировать client_id и client_secret. Полученную пару передайте в finish_login. Предупредите, что client_secret — это пароль от рекламного кабинета: он сохранится на диске только для владельца и нужен, чтобы продлевать токен.

Takes no parameters.

Второй шаг подключения: обменивает client_id и client_secret из start_login на токен доступа (grant client_credentials), сохраняет всё в файл только для владельца (0600) и сразу проверяет живым запросом к VK Рекламе. После успеха остальные инструменты работают немедленно — перезапускать клиент не нужно. Токен живёт около суток и продлевается автоматически, поэтому повторно вызывать это не требуется: каждый вызов создаёт НОВЫЙ токен, а у VK не больше 5 активных токенов на пару client_id + пользователь. Ошибка invalid_client означает, что пара скопирована не полностью или относится к разным приложениям.

Удаляет сохранённые токен и данные приложения VK Рекламы с диска. Токен, заданный переменной окружения VK_ADS_TOKEN, не трогает — его нужно убирать из конфигурации клиента вручную. На стороне VK токен остаётся активным до истечения срока: отозвать его можно запросом POST v2/oauth2/token/delete.json, но он удаляет ВСЕ токены этого пользователя для данного client_id, поэтому здесь не вызывается.

Takes no parameters.

Возвращает информацию о текущем аккаунте VK Рекламы (user.json), включая additional_info.client_name. Позволяет убедиться, на какой аккаунт рекламодателя указывает токен. Токен гранта client_credentials агентского аккаунта видит объекты самого агентства, а не его клиентов: кабинет клиента открывает только токен гранта agency_client_credentials в VK_ADS_TOKEN.

Возвращает текущий баланс аккаунта VK Рекламы: доступные средства и валюту. Вызывает user.json с полем `account`, в котором лежит кошелёк (account.balance, account.currency). Показывает баланс того аккаунта, на который указывает токен (параметров нет). Важно: точное имя поля с балансом в v3/user.json на новой платформе ads.vk.com не подтверждено на живом кабинете (домен закрыт JS); схема следует объектной модели myTarget/VK Ads (v2/v3). Инструмент отдаёт СЫРОЙ ответ VK без изменений, поэтому вызывающая сторона может аккуратно прочитать account.balance независимо от точной формы ответа — проверить на первом живом аккаунте с доступом read_payments.

Takes no parameters.

Возвращает текущие лимиты запросов VK Рекламы и их остаток (throttling.json) — чтобы не упереться в лимит.

Takes no parameters.

Возвращает гео-регионы VK Рекламы (id, name, type), при необходимости отфильтрованные по подстроке названия. Id регионов нужны для гео-таргетинга группы объявлений.

Возвращает список ad_plan (верхнеуровневый объект кампании в VK Рекламе) с необязательной фильтрацией по id и статусу. Денежные поля (budget_limit, budget_limit_day, max_price) — в валюте аккаунта.

Создаёт кампанию (ad_plan). Денежные поля — в валюте аккаунта. Сложные и редкие поля передаются через `extra` (подмешиваются в тело запроса как есть). Пустую кампанию VK не создаёт: в `adGroups` нужен массив новых групп объявлений, у каждой — name, package_id, targetings, а для autobiddingMode=max_goals ещё priced_goal {source_id: id счётчика, name: цель}. Следующие группы добавляет create_ad_group. Кампании на сайт нужна привязка `extra.ad_object_type`="url" + `extra.ad_object_id` (id URL-объекта; без неё любой package_id отвергается как invalid_package) — проще всего взять ad_object_id, package_id и priced_goal у существующей кампании и её групп (list_ad_plans / list_ad_groups с нужными fields). budgetLimit и budgetLimitDay одновременно передавать нельзя — только одно из двух. Чтобы ничего не запустилось, передать status="blocked" и в `extra`, и у каждой группы в `adGroups`.

Меняет у кампании название, бюджеты, предельную ставку или даты. Денежные поля — в валюте аккаунта. Для смены статуса — ad_plan_action.

Меняет статус кампаний по id: activate (status=active), stop (status=blocked) или delete (status=deleted). delete удаляет только саму кампанию: её группы и объявления остаются в прежнем статусе — их удаляют отдельно через ad_group_action и banner_action.

Возвращает список групп объявлений с необязательной фильтрацией по id, родительской кампании и статусу. Денежные поля — в валюте аккаунта; в `targetings` лежит структура таргетинга по гео, демографии и интересам.

Создаёт группу объявлений внутри кампании. Таргетинг задаётся в `targetings` (например, {"geo":{"regions":[188]},"age":{"age_list":[25,26]}}). Денежные поля — в валюте аккаунта. Остальные поля — через `extra`.

Меняет у группы объявлений название, бюджеты, предельную ставку, даты или таргетинг. Денежные поля — в валюте аккаунта. Для смены статуса — ad_group_action.

Меняет статус групп объявлений по id: activate (status=active), stop (status=blocked) или delete (status=deleted).

Возвращает список banner (объект объявления/креатива в VK Рекламе) с необязательной фильтрацией по id, родительской группе объявлений и статусу. moderation_status (pending/allowed/banned) и delivery объясняют, почему объявление показывается или не показывается.

Создаёт объявление внутри группы объявлений (POST v2/ad_groups/{adGroupId}/banners.json; верхний v2/banners.json — только список). Креатив ссылается на загруженные медиа через `content`, тексты объявления — в `textblocks`, ссылки — в `urls`. Эти структуры отправляются как есть; точная форма для каждого формата объявления — в документации VK Рекламы.

Меняет у объявления название, текстовые блоки или ссылки. Для смены статуса — banner_action. Структуры отправляются как есть.

Меняет статус объявлений по id: activate (status=active), stop (status=blocked) или delete (status=deleted).

Загружает изображение JPEG или PNG в медиатеку VK Рекламы (multipart POST v2/content/static.json) и возвращает его id и variants. Этот id передаётся в create_banner как content.<слот>={"id": <id>}; какие слоты нужны, зависит от формата (package) группы. Размер картинки должен подходить слоту: например, image_600x600 принимает не шире 600 px, иначе create_banner получит bad_width. Байты передаются base64 без префикса data:, вместе с шириной и высотой картинки в пикселях. При сетевой ошибке или 5xx загрузка могла пройти — не повторять вслепую.

Возвращает статистику по кампаниям (ad_plans), группам объявлений (ad_groups) или объявлениям (banners). По умолчанию группировка `summary` — одна сводная строка (`items[].total`) на объект: с dateFrom/dateTo — за этот период, без дат — за всё время. `day` нужна ТОЛЬКО для динамики и вопросов про тренд: добавляет к каждому объекту `rows` по дням, даты обязательны. Недель и месяцев API не отдаёт — их собирают из `day`. Ранжирование на стороне сервера (sortBy, например base.spent, и order) и постраничная выдача (limit/offset) работают только в `summary` с датами — в остальных режимах VK их молча игнорирует, поэтому инструмент вернёт ошибку. Там VK и так отдаёт все объекты одним ответом, так что autoPaginate безвреден в любом режиме. `total` в ответе — сумма по объектам ЭТОЙ страницы (при фильтре по ids — по этим объектам), а не по всему кабинету. Метрики лежат в `base` (shows, clicks, spent, ...); spent — в валюте аккаунта.

Универсальный запрос напрямую к любому эндпоинту API VK Рекламы (например, path "v2/ad_plans.json", method GET). Нужен для эндпоинтов, у которых нет отдельного инструмента. `query` уходит в строку запроса, `body` отправляется как JSON для POST. GET выполняется свободно; POST и DELETE — запись, для них нужен confirmWrite=true.