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.
Анализ и рекомендации
Сервер не только отдаёт данные, но и помогает их разобрать по схемеанализ → ранжирование → рекомендации:
- Анализ.
list_campaignsиget_statisticsдают структуру и цифры за период.Ресурсыvk-ads://metricsиvk-ads://objectsобъясняют, что значат метрики и поля. - Ранжирование.
get_top_objectsпоказывает лучшие и худшие объекты по нужнойметрике:order=descдля CTR и конверсий,order=ascдляcpc/cpa, где меньше — лучше. - Рекомендации. Промпт
campaign_analysisсобирает шаги в готовый сценарий:на что смотреть, что отключить, где поднять ставку.
Доступ к API
client_id/client_secret не выдаются автоматически. В кабинете VK Рекламы:Настройки → Доступ к API → Запросить доступ к API (или письмо на[email protected]). 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
