# vk-ads-mcp

MCP-сервер для Claude Code: отдаёт статистику и структуру рекламных кампаний
VK Рекламы (новый кабинет `ads.vk.com`, база `https://ads.vk.com/api/v2`).

Только чтение. Ничего не создаёт и не меняет. Рассчитан на свой кабинет.

Под капотом — тот же движок, что у myTarget. Словарь объектов:
`ad_plans` — кампании, `ad_groups` — группы объявлений, `banners` — объявления.

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

| Инструмент | Что делает |
|---|---|
| `list_campaigns` | список кампаний (`ad_plans`), фильтр по статусу, пагинация |
| `list_ad_groups` | список групп объявлений, фильтр по кампании |
| `list_banners` | список объявлений, фильтр по группе |
| `get_statistics` | статистика по `ad_plans`/`ad_groups`/`banners` за период (`day`/`summary`); сам режет диапазон >92 дней и список >50 id на части |
| `get_top_objects` | топ кампаний / групп / объявлений по метрике (`ctr`, `cpc`, `cpa`, `spent` и т.д.); `order=asc` — для метрик стоимости |
| `describe_fields` | список допустимых полей для `ad_plans`/`ad_groups`/`banners` — узнаёт их у API на лету |
| `export_to_csv` | выгрузка статистики в CSV-файл |
| `get_rate_limits` | остаток квоты API для диагностики |

Списочные инструменты по умолчанию отдают минимальный набор полей. Чтобы получить
больше данных, передайте `fields` (через запятую). Какие поля доступны для объекта —
подскажет `describe_fields`.

## Ресурсы и промпт

| Ресурс | Что внутри |
|---|---|
| `vk-ads://metrics` | справочник групп метрик статистики (`base`, `uniques`, `video`, `events`, `viral`, `carousel`, `tps`, `romi`, `moat`, `playable`) с единицами измерения |
| `vk-ads://objects` | иерархия `ad_plans → ad_groups → banners` и ключевые поля для анализа |

Промпт `campaign_analysis` — пошаговый сценарий разбора кампаний на русском.
Принимает необязательные `date_from`, `date_to`, `objective`.

## Анализ и рекомендации

Сервер не только отдаёт данные, но и помогает их разобрать по схеме
**анализ → ранжирование → рекомендации**:

1. **Анализ.** `list_campaigns` и `get_statistics` дают структуру и цифры за период.
   Ресурсы `vk-ads://metrics` и `vk-ads://objects` объясняют, что значат метрики и поля.
2. **Ранжирование.** `get_top_objects` показывает лучшие и худшие объекты по нужной
   метрике: `order=desc` для CTR и конверсий, `order=asc` для `cpc`/`cpa`, где меньше — лучше.
3. **Рекомендации.** Промпт `campaign_analysis` собирает шаги в готовый сценарий:
   на что смотреть, что отключить, где поднять ставку.

## Доступ к API

`client_id`/`client_secret` не выдаются автоматически. В кабинете VK Рекламы:
**Настройки → Доступ к API → Запросить доступ к API** (или письмо на
`ads_api@vk.team`). `client_secret` показывают один раз. Подробнее —
в исходном обзоре `../Open-Source решения для MCP Server VK Ads — полный обзор.md`.

## Настройка

Скопируйте `.env.example` в `.env` и задайте пару из кабинета:

```
VK_ADS_CLIENT_ID=...
VK_ADS_CLIENT_SECRET=...
```

Сервер сам получит и обновит токен через `grant_type=client_credentials`
(и перезапросит при 401). Если когда-нибудь окажется готовый Bearer-токен —
можно вместо пары задать `VK_ADS_TOKEN`, тогда OAuth не используется.

`.env` в git не попадает. `.mcp.json` хранит только плейсхолдеры
`${VK_ADS_CLIENT_ID}` / `${VK_ADS_CLIENT_SECRET}`.

VK ограничивает кабинет 5 живыми токенами на `client_id`, а Claude Code часто
перезапускает сервер. Поэтому токен кешируется на диск
(`~/.cache/vk-ads-mcp/token.json`, права `0600`) и переиспользуется между
перезапусками — новый токен не выпускается, пока старый не истёк. Путь меняется
через `VK_ADS_TOKEN_CACHE`.

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

```sh
claude mcp add vk-ads --scope project \
  --env VK_ADS_CLIENT_ID=$VK_ADS_CLIENT_ID \
  --env VK_ADS_CLIENT_SECRET=$VK_ADS_CLIENT_SECRET \
  -- uv run --with fastmcp fastmcp run src/vk_ads_mcp/server.py
```

Команда дописывает `.mcp.json` в корень проекта (он уже здесь). Реальный токен
берётся из окружения при запуске, в репозиторий не коммитится.

## Разработка

```sh
uv sync --all-extras --dev
uv run pytest -q          # тесты, сеть не нужна (httpx замокан через respx)
uv run ruff check .       # линт
uv run ruff format .      # форматирование
```

## Отладка вручную

```sh
uv run fastmcp dev src/vk_ads_mcp/server.py
```

Поднимает MCP Inspector — можно дёргать инструменты руками и смотреть ответы.

## Структура

```
src/vk_ads_mcp/
  app.py          общий FastMCP-инстанс + ленивый клиент
  config.py       чтение env
  auth.py         OAuth2 client_credentials + refresh / Bearer-override
  client.py       весь HTTP: пагинация, чанкинг 92 дней / 50 id, бэкофф на 429
  models.py       pydantic-модели ответов
  tools/          по файлу на инструмент
  resources.py    ресурсы vk-ads://metrics и vk-ads://objects
  prompts.py      промпт campaign_analysis
  server.py       точка входа (регистрирует инструменты, ресурсы, промпт, запускает stdio)
tests/            pytest + respx
```