# 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 Рекламы и расход за прошлую неделю по группам объявлений.

[Подключить сервер](#быстрый-старт) · [Посмотреть сценарии](#что-можно-поручить) · [Открыть техническую документацию](#техническая-документация)

---

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

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

## Содержание

- [Быстрый старт](#быстрый-старт)
- [Что можно поручить](#что-можно-поручить)
- [Как устроены объекты VK Рекламы](#как-устроены-объекты-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`. Переменные окружения не нужны: кабинет подключается в диалоге.

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

```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)

</details>

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

<br>

```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)

</details>

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

<br>

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

</details>

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

<br>

Для всех проектов создайте `~/.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)

</details>

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

<br>

Откройте палитру команд и выполните **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)

</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](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`. |

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

<br>

```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`.

</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-возможностей](./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).