VK Реклама MCP

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

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

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

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

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

---

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

<img src="docs/demo.gif" alt="Демонстрация: ассистент сопоставляет кампании, статистику и баланс VK Рекламы" width="1000">

Содержание

• Быстрый старт
• Что можно поручить
• Как устроены объекты VK Рекламы
• Что может изменить данные
• Подключение кабинета
• Настройка
• Данные, лимиты и работа в фоне
• Техническая документация
• Поддержка

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

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

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

<details open> <summary><strong>Codex</strong></summary> <br>

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

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

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

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

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

codex mcp list

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

</details> <details> <summary><strong>Claude Code</strong></summary> <br>

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

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

claude mcp list

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

</details> <details> <summary><strong>Claude Desktop</strong></summary> <br>

Откройте 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.

</details> <details> <summary><strong>Cursor</strong></summary> <br>

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

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

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

</details> <details> <summary><strong>VS Code</strong></summary> <br>

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

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

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

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

</details>

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

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

• «Покажи расход, показы, клики и 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. |

<details> <summary>Как выпустить токен для <code>VK_ADS_TOKEN</code> вручную</summary> <br>

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.

</details>

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

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