vk-ads-mcp

# MCP «ВК Реклама»

<!-- mcp-name: io.github.ai-hub-open/vk-ads-mcp -->

MCP-сервер на Bun и TypeScript, который даёт ИИ-агенту прямой доступ к [API ВК Рекламы](https://ads.vk.com/) (myTarget API v2).

## Что это

Из диалога с вами агент читает состояние аккаунта и вносит изменения через API: смотрит кампании, группы и объявления, выгружает статистику со срезами, создаёт и правит сущности, загружает креативы, собирает аудитории для ремаркетинга, отправляет объявления на модерацию, запускает и останавливает показы.

Стратегию и тексты объявлений сервер не придумывает — он исполняет решения, которые принимаете вы вместе с агентом. В наборе 48 инструментов.

## Как проходит работа

1. **Подключение и доступ.** Вы выбираете готовый токен ВК Рекламы, OAuth-приложение или подключение через Click.ru. Проверить связь можно инструментом `auth_check`. Сервер работает локально через стандартный ввод-вывод или по HTTP, в том числе с несколькими аккаунтами.
2. **Чтение состояния.** Перед изменением агент получает кампании, группы, объявления, справочники и текущую статистику.
3. **Изменение.** Агент создаёт и правит сущности, загружает изображения и видео, собирает аудитории и списки клиентов, отправляет объявления на модерацию и меняет статусы.
4. **Проверка.** После изменения агент снова читает состояние и статистику.

Сервер не запускает кампании самостоятельно. Показ включается только отдельной явной сменой статуса.

## Инструменты

| Область | Что позволяет сделать |
|---|---|
| **Авторизация и аккаунт** | Проверить доступ, получить данные аккаунта и отозвать лишние OAuth-токены |
| **Кампании — API `ad_plans`** | Создавать и вести кампании верхнего уровня, задавать сроки и ограничения бюджета |
| **Группы объявлений — API `campaigns`** | Создавать группы с целью, бюджетом и таргетингом, запускать и останавливать показы |
| **Дополнительные группы — API `ad_groups`** | Группировать объявления по таргетингу |
| **Объявления — API `banners`** | Создавать и править объявления, привязывать креативы и отправлять на модерацию |
| **Контент** | Загружать изображения и видео из локального файла или по URL |
| **Статистика** | Получать данные по дням, итоги за период, срезы и большие асинхронные отчёты |
| **Ремаркетинг** | Работать с сегментами, пикселями и списками пользователей |
| **Агентство** | Получать список клиентов и создавать клиентов агентского аккаунта |
| **Справочники** | Искать регионы, пакеты форматов, интересы, браузеры, валюты и отрасли |

### Терминология API

В новом интерфейсе ВК Рекламы и API одни и те же уровни называются по-разному:

| В интерфейсе | В API |
|---|---|
| Кампания | `ad_plan` |
| Группа объявлений | `campaign` |
| Объявление | `banner` |

Группа `campaign`, созданная без `ad_plan_id`, становится «сиротой» и не видна в новом кабинете. Создавайте группы внутри кампании или сразу передавайте `ad_plan_id`.

## Что делает агент, а что остаётся человеку

**Сервер и агент:**

- получают и обновляют токен доступа;
- читают состояние аккаунта и справочники;
- создают, правят и загружают сущности по вашему заданию;
- получают статистику и проверяют результат изменения.

**Человек:**

- выдаёт токен или ключи доступа;
- выбирает бюджет, таргетинг, креативы, тексты и аудитории;
- подтверждает план до создания, правки или удаления;
- отдельным решением запускает показы и отправляет объявления на модерацию.

У сервера нет встроенной точки подтверждения: вызов на изменение уходит в API сразу. Кампании, группы и объявления удаляются мягко через статус `deleted`; удаление сегментов, пикселей и списков пользователей необратимо на стороне API.

## Ограничения

- Сервер не пишет стратегию и не придумывает креативы.
- В наборе нет инструментов для создания лид-форм.
- API не позволяет получить список ранее загруженных изображений и видео.
- Похожие аудитории и группы ремаркетинга недоступны; используйте сегменты, пиксели и списки пользователей.
- Сервер не гарантирует прохождение модерации.
- ВК ограничивает число активных OAuth-токенов: при превышении лишние токены нужно отозвать.
- Операции чтения проверялись на живом API выборочно. Создание, правка и удаление покрыты автоматическими тестами, но перед работой с важным аккаунтом их стоит проверить на безопасном объекте.

## Требования

- [Bun](https://bun.sh) 1.1+

## Установка

Из npm — одной командой (нужен установленный Bun):

```bash
bunx @ai-hub-open/vk-ads-mcp
```

Для подключения в конфиге MCP-клиента: `"command": "bunx", "args": ["@ai-hub-open/vk-ads-mcp"]` плюс переменные окружения одного из режимов ниже.


```bash
git clone https://github.com/ai-hub-open/vk-ads-mcp.git
cd vk-ads-mcp
bun install
```

## Настройка

Скопируйте `.env.example` в `.env` и заполните **один из вариантов** (переменные окружения имеют приоритет над `.env`):

**A. Через [Click.ru](https://click.ru) — основной путь: токен без заявок на доступ к API, свои ключи ВК не нужны:**

```bash
CLICK_RU_TOKEN=<API-токен из профиля click.ru>
CLICK_RU_ACCOUNT_ID=<ID рекламного аккаунта VK Рекламы в Click.ru>
CLICK_RU_USER_ID=<ID пользователя click.ru>   # только при работе из мастер-аккаунта
```

Сервер сам запрашивает access_token VK Ads у Click.ru, кэширует и обновляет его при `401`. Токен Click.ru создаётся в профиле `https://click.ru/userinfo.html` → поле «API Token» → «Создать»; ID аккаунта VK Рекламы — через `GET /accounts` в `https://api.click.ru/V0/docs/`. Справка: `https://help.click.ru/2327`, `https://help.click.ru/4814`.

**B. Готовый access_token VK Ads:**

```bash
VK_ADS_ACCESS_TOKEN=eyJ0...
```

Токен: [ads.vk.com](https://ads.vk.com/) → Настройки профиля → Получить токен / API.

**C. OAuth 2.0 Client Credentials — приложение, одобренное на [target.vk.ru](https://target.vk.ru/):**

```bash
VK_ADS_CLIENT_ID=12345
VK_ADS_CLIENT_SECRET=abcdef...
# VK_ADS_AGENCY_CLIENT_NAME=<username клиента>  # агентство от имени клиента
```

Сервер сам получает токен (`grant_type=client_credentials` / `agency_client_credentials`), кэширует на диске и обновляет при `401`. При ошибке `token_limit_exceeded` (у VK лимит ≤5 активных токенов) используйте инструмент `vk_ads_token_revoke`.

## Запуск

```bash
bun run src/index.ts          # stdio — для локальных MCP-клиентов
bun run src/index.ts --http   # HTTP-сервер на :3000
```

## Подключение к Claude Code

`.mcp.json` в корне вашего проекта (см. также `.mcp.json.example`):

```json
{
  "mcpServers": {
    "vk-ads": {
      "command": "bun",
      "args": ["run", "/абсолютный/путь/к/vk-ads-mcp/src/index.ts"],
      "env": {
        "CLICK_RU_TOKEN": "<ваш токен>",
        "CLICK_RU_ACCOUNT_ID": "<ID аккаунта VK Рекламы>"
      }
    }
  }
}
```

Для режима готового токена в `env` вместо `CLICK_RU_*` укажите `VK_ADS_ACCESS_TOKEN`.

**📋 Инструкция для AI-агента** — скопируйте и передайте своему агенту (Claude Code / Codex), подставив ключи:

> Установи и подключи MCP-сервер «VK Ads»: склонируй `https://github.com/ai-hub-open/vk-ads-mcp.git`, проверь Bun (`bun --version`, если нет — установи с https://bun.sh), выполни `bun install` в корне репозитория. Зарегистрируй локальный stdio-MCP: команда `bun`, аргументы `run <абсолютный_путь_к_репо>/src/index.ts`, переменные окружения — мои ключи: `CLICK_RU_TOKEN=<...>`, `CLICK_RU_ACCOUNT_ID=<...>` (или `VK_ADS_ACCESS_TOKEN=<...>` для режима готового токена). Проверь `tools/list` и сообщи результат.

## HTTP-режим

```bash
MCP_TRANSPORT=http MCP_PORT=3000 bun run src/index.ts
```

Переменные: `MCP_PORT` (3000), `MCP_HOST` (0.0.0.0), `MCP_AUTH_TOKEN` (если задан — запросы должны нести `Authorization: Bearer <token>`), `MCP_ALLOWED_ORIGIN` (CORS).

| Метод + путь | Назначение |
|---|---|
| `POST /mcp` | JSON-RPC 2.0 запрос (или батч) |
| `GET /healthz` | health check |
| `GET /mcp/tools` | список инструментов (отладка) |

**Несколько аккаунтов:** данные доступа можно передавать в заголовках каждого запроса; они имеют приоритет над `.env`. Один сервер может обслуживать несколько клиентов:

```
X-VK-Ads-Token: <access_token>       X-Click-Ru-Token: <API-токен>
                                     X-Click-Ru-Account-Id: <ID аккаунта VK Рекламы>
X-VK-Ads-Client-Id: <client_id>      X-Click-Ru-User-Id: <ID пользователя>
X-VK-Ads-Client-Secret: <secret>     X-Click-Ru-Base-Url: <опционально>
X-VK-Ads-Agency-Client-Name: <...>   X-VK-Ads-Base-Url: <опционально>
```

Сервер можно запустить без данных доступа в `.env` — тогда они передаются в каждом запросе. Полученные через OAuth или Click.ru токены сохраняются в памяти и на диске отдельно для каждого набора доступа.

**⚠️ Безопасность:** при публикации в сеть задайте `MCP_AUTH_TOKEN` и закройте порт за обратным прокси-сервером с TLS.

## Docker

```bash
cp .env.example .env   # заполните ключи и MCP_AUTH_TOKEN
docker compose up -d --build
curl http://localhost:3000/healthz
```

## Тесты

```bash
bun test                        # 54 теста: клиент, сервер, инструменты (без сети)
bun run typecheck               # tsc --noEmit
bun run scripts/live-check.ts   # проверка чтения через реальный API (нужны данные доступа)
```

## Лицензия

[Apache License 2.0](LICENSE)