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

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 в корень проекта (он уже здесь). Реальный токен берётся из окружения при запуске, в репозиторий не коммитится.

Разработка

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

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

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