@theyahia/vk-ads-mcp

MCP-сервер для VK Ads API v2 (ads.vk.com/api/v2) — кампании, группы объявлений, объявления, статистика, баланс. 8 инструментов.

Модель данных VK Ads: ad_plans (кампании) → ad_groups (группы) → banners (объявления). Имена инструментов оставлены дружелюбными (list_campaigns, list_ads), но обращаются к реальным v2-ресурсам.

Установка

Claude Desktop

{
  "mcpServers": {
    "vk-ads": {
      "command": "npx",
      "args": ["-y", "@theyahia/vk-ads-mcp"],
      "env": {
        "VK_ADS_TOKEN": "ваш_токен"
      }
    }
  }
}

Claude Code

claude mcp add vk-ads -e VK_ADS_TOKEN=ваш_токен -- npx -y @theyahia/vk-ads-mcp

Related MCP server: vk-ads-mcp

Авторизация

access_token живёт ~1 день. Если заданы все три refresh-переменные, сервер на 401 сам обновит токен через grant_type=refresh_token. Иначе — обновляйте VK_ADS_TOKEN вручную.

Кабинет выбирается токеном, а не параметром. В VK Ads v2 нет account_id в запросах: агентство/менеджер получает отдельный per-client токен (agency_client_credentials) и подписывает им запросы нужного кабинета.

Инструменты (8)

Все инструменты используют MCP-аннотации (readOnlyHint/destructiveHint/idempotentHint), а read-инструменты — outputSchema + structuredContent для типизированного и компактного ответа. Списки пагинируются автоматически (до 200 объектов; больше — флаг truncated в ответе).

Примеры запросов

Покажи активные кампании
Создай кампанию "Осенняя акция" с целью traffic и бюджетом 50000
Останови кампанию 12345
Какие группы объявлений в кампании 12345?
Статистика кампании 12345 за январь 2026 по дням
Покажи баланс кабинета

Миграция 1.x → 2.0 (breaking)

Версия 1.x обращалась к легаси API (/campaigns.json, /ads.json, плоский /statistics.json, account_id, числовые статусы) и фактически не работала против ads.vk.com/api/v2. В 2.0 переписан весь API-слой:

• account_id удалён из всех инструментов — кабинет задаётся токеном.

• update_campaign: вместо status: 1/0 → action: activate|stop|delete (строковые статусы active/blocked/deleted).

• Бюджет: all_limit → budget_limit / budget_limit_day (валюта кабинета, не копейки).

• create_campaign: type → objective (цель кампании).

• create_ad: вместо {ad_format,title,description,link_url} → {ad_group_id, textblocks, urls, content}.

• get_statistics: ids_type/period=week|month|overall → object_type и period=day|summary в пути URL.

• list_targeting_groups → list_ad_groups (таргетинг живёт на группе объявлений).

• get_budget → get_account (баланс читается из /user.json).

Точность API

Эндпоинты и поля подтверждены официальной документацией target.vk.ru и 5 независимыми рабочими клиентами. Несколько деталей помечены в коде // VERIFY: (единицы бюджета, поле баланса, полный enum objective, путь update) и требуют подтверждения живым токеном — см. docs/VERIFICATION.md (~10 минут).

Возможный follow-up (вне текущего объёма)

Массовые действия (mass_action), список клиентов агентства (agency/clients), загрузка креативов (upload_creative), состояние лимитов (throttling), справочники таргетинга (regions/interests), конверсии и remarketing-аудитории.

Разработка

npm install
npm run build      # tsc
npm test           # vitest
npm run dev        # tsx src/index.ts (читает .env — см. .env.example)

Лицензия

MIT