# 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. Можно спросить, какие кампании тратят бюджет без результата, сравнить группы и объявления, подготовить новую кампанию или изменить ставку. В отличие от ручного перехода по разделам кабинета, ассистент сопоставляет кампании, статистику, баланс и статусы в одном диалоге. - **18 инструментов.** Кампании, группы, объявления, статистика, баланс, лимиты API, регионы и универсальный запрос к API. - **Живая реклама.** Ставки, бюджеты и расход отображаются в валюте рекламного кабинета — без пересчёта микроединиц. - **Полная иерархия.** Кампания (`ad_plan`) → группа (`ad_group`) → объявление (`banner`). - **Сначала анализ.** Списки, отчёты, баланс и статусы доступны только на чтение. - **Изменения — в боевом кабинете.** Создание, обновление и действия со статусами применяются сразу; у VK Ads нет песочницы. Начните с безопасного запроса: > Покажи кампании моего аккаунта VK Рекламы и расход за прошлую неделю по группам объявлений. [Подключить сервер](#быстрый-старт) · [Посмотреть сценарии](#что-можно-поручить) · [Открыть техническую документацию](#техническая-документация) --- ## Увидеть работу за минуту Демонстрация: ассистент сопоставляет кампании, статистику и баланс VK Рекламы ## Содержание - [Быстрый старт](#быстрый-старт) - [Что можно поручить](#что-можно-поручить) - [Как устроены объекты VK Рекламы](#как-устроены-объекты-vk-рекламы) - [Что может изменить данные](#что-может-изменить-данные) - [Как получить токен](#как-получить-токен) - [Настройка](#настройка) - [Данные, лимиты и работа в фоне](#данные-лимиты-и-работа-в-фоне) - [Техническая документация](#техническая-документация) - [Поддержка](#поддержка) ## Быстрый старт Нужны Node.js 20 или новее и access-токен VK Ads. Сервер запускается через `npx`, поэтому отдельно устанавливать пакет не требуется. 1. [Получите токен](#как-получить-токен) и добавьте сервер в AI-приложение — инструкции для пяти приложений ниже. 2. Спросите: «Покажи кампании моего аккаунта VK Рекламы и расход за прошлую неделю по группам объявлений».
Codex
**Через интерфейс приложения:** 1. Откройте **Settings → Plugins → MCP servers**. 2. Нажмите **Add server**. 3. Добавьте команду запуска `npx -y mcp-vk-ads@latest` и переменную окружения `VK_ADS_TOKEN` со своим токеном. **Через командную строку:** ```bash codex mcp add vk-ads \ --env VK_ADS_TOKEN=ваш_токен \ -- 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 \ --env VK_ADS_TOKEN=ваш_токен \ --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"], "env": { "VK_ADS_TOKEN": "ваш_токен" } } } } ``` Если **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"], "env": { "VK_ADS_TOKEN": "ваш_токен" } } } } ``` [Документация 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"], "env": { "VK_ADS_TOKEN": "${input:vk_ads_token}" } } }, "inputs": [ { "type": "promptString", "id": "vk_ads_token", "description": "Access-токен VK Ads", "password": true } ] } ``` Проверьте запуск командой **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` не повторяйте создание вслепую: операция могла успеть примениться, сначала проверьте список объектов. ## Как получить токен Токен выдаёт кабинет VK Ads: 1. В [ads.vk.com](https://ads.vk.com) откройте **Настройки → Доступ к API** и создайте приложение. Сохраните `client_id` и `client_secret`. Если раздел недоступен, запросите доступ к API у поддержки VK Ads. 2. Обменяйте их на access-токен кабинета: ```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 ``` 3. Возьмите `access_token` из ответа и сохраните его как `VK_ADS_TOKEN`. Токен даёт доступ к рекламному кабинету, включая возможность тратить бюджет, и хранится в конфигурации MCP-клиента открытым текстом. Относитесь к нему как к паролю. Если API отвечает `invalid_token`, выпустите и укажите новый токен. Для агентств, работающих с кабинетами клиентов, нужен сценарий `authorization_code` — см. [документацию VK Ads API](https://ads.vk.com/doc/api). ## Настройка | Переменная | Назначение | |---|---| | `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`. | ## Данные, лимиты и работа в фоне - **Страницы и большие кабинеты.** Одна страница списка содержит до 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).