# VK Реклама MCP [![npm](https://img.shields.io/npm/v/mcp-vk-ads)](https://www.npmjs.com/package/mcp-vk-ads) [![CI](https://github.com/askads/mcp-vk-ads/actions/workflows/ci.yml/badge.svg)](https://github.com/askads/mcp-vk-ads/actions/workflows/ci.yml) [![Glama](https://glama.ai/mcp/servers/askads/mcp-vk-ads/badges/score.svg)](https://glama.ai/mcp/servers/askads/mcp-vk-ads) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE) **VK Реклама MCP** подключает AI-приложение к рекламному кабинету VK Ads. Можно спросить, какие кампании тратят бюджет без результата, сравнить группы и объявления, подготовить новую кампанию или изменить ставку. В отличие от ручного перехода по разделам кабинета, ассистент сопоставляет кампании, статистику, баланс и статусы в одном диалоге. - **22 инструмента.** Кампании, группы, объявления, статистика, баланс, лимиты API, регионы, подключение кабинета и универсальный запрос к API. - **Подключение из диалога.** Скажите «подключи ВК Рекламу» — сервер объяснит, где взять `client_id` и `client_secret`, получит токен и дальше продлевает его сам. - **Живая реклама.** Ставки, бюджеты и расход отображаются в валюте рекламного кабинета — без пересчёта микроединиц. - **Полная иерархия.** Кампания (`ad_plan`) → группа (`ad_group`) → объявление (`banner`). - **Сначала анализ.** Списки, отчёты, баланс и статусы доступны только на чтение. - **Изменения — в боевом кабинете.** Создание, обновление и действия со статусами применяются сразу; у VK Ads нет песочницы. Начните с безопасного запроса: > Покажи кампании моего аккаунта VK Рекламы и расход за прошлую неделю по группам объявлений. [Подключить сервер](#быстрый-старт) · [Посмотреть сценарии](#что-можно-поручить) · [Открыть техническую документацию](#техническая-документация) --- ## Увидеть работу за минуту Демонстрация: ассистент сопоставляет кампании, статистику и баланс VK Рекламы ## Содержание - [Быстрый старт](#быстрый-старт) - [Что можно поручить](#что-можно-поручить) - [Как устроены объекты VK Рекламы](#как-устроены-объекты-vk-рекламы) - [Что может изменить данные](#что-может-изменить-данные) - [Подключение кабинета](#подключение-кабинета) - [Настройка](#настройка) - [Данные, лимиты и работа в фоне](#данные-лимиты-и-работа-в-фоне) - [Техническая документация](#техническая-документация) - [Поддержка](#поддержка) ## Быстрый старт Нужен Node.js 20 или новее. Сервер запускается через `npx`, поэтому отдельно устанавливать пакет не требуется; токен при установке не нужен. 1. Добавьте сервер в AI-приложение — инструкции для пяти приложений ниже. 2. Скажите: «Подключи ВК Рекламу» — сервер проведёт [подключение](#подключение-кабинета) прямо в диалоге. 3. Спросите: «Покажи кампании моего аккаунта VK Рекламы и расход за прошлую неделю по группам объявлений».
Codex
**Через интерфейс приложения:** 1. Откройте **Settings → Plugins → MCP servers**. 2. Нажмите **Add server**. 3. Добавьте команду запуска `npx -y mcp-vk-ads@latest`. Переменные окружения не нужны: кабинет подключается в диалоге. **Через командную строку:** ```bash codex mcp add vk-ads -- npx -y mcp-vk-ads@latest ``` Проверьте подключение: ```bash codex mcp list ``` [Официальная инструкция Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)
Claude Code
```bash claude mcp add \ --transport stdio \ --scope user \ vk-ads \ -- npx -y mcp-vk-ads@latest ``` Проверьте сервер: ```bash claude mcp list ``` [Документация Claude Code](https://docs.anthropic.com/en/docs/claude-code/mcp)
Claude Desktop
Откройте **Settings → Developer → Edit Config** и добавьте сервер в `claude_desktop_config.json`: ```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`: ```json { "mcpServers": { "vk-ads": { "command": "npx", "args": ["-y", "mcp-vk-ads@latest"] } } } ``` [Документация Cursor](https://docs.cursor.com/context/model-context-protocol)
VS Code
Откройте палитру команд и выполните **MCP: Open User Configuration**. Добавьте в `mcp.json`: ```json { "servers": { "vk-ads": { "type": "stdio", "command": "npx", "args": ["-y", "mcp-vk-ads@latest"] } } } ``` Проверьте запуск командой **MCP: List Servers**. [Документация VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
## Что можно поручить ### Разобраться с расходом и результатом - «Покажи расход, показы, клики и 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](https://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](https://ads.vk.com/doc/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 вручную
```bash 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-возможностей](./docs/capabilities/index.md) — страницы по пользовательским задачам для каждого инструмента. - [Все инструменты и параметры](./docs/TOOLS.md) - [Документация по разработке](./docs/DEVELOPMENT.md) - [Пакет в npm](https://www.npmjs.com/package/mcp-vk-ads) - [Документация VK Ads API](https://ads.vk.com/doc/api) ## Поддержка Нашли ошибку или не хватает сценария? [Создайте issue](https://github.com/askads/mcp-vk-ads/issues) или напишите в [Telegram](http://t.me/gistrec).