Skip to main content
Glama
vk-ads-mcp

vk-ads-mcp

by theYahia

VK Ads MCP — управление рекламой ВКонтакте через нейросеть

Если вы искали, как подключить рекламный кабинет VK Ads к ИИ-ассистенту, спрашивать про открутку и остаток бюджета обычными словами или собирать отчёты по кампаниям без выгрузок в Excel — это оно. 8 инструментов поверх VK Ads API v2 (ads.vk.com/api/v2): кампании, группы объявлений, объявления, статистика и баланс.

npm License: MIT

Модель данных 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: Meta Ads MCP Server

Авторизация

Переменная

Обязательна

Назначение

VK_ADS_TOKEN

✅

OAuth2 Bearer access_token VK Ads API

VK_ADS_CLIENT_ID

—

для авто-обновления токена (refresh)

VK_ADS_CLIENT_SECRET

—

для авто-обновления токена (refresh)

VK_ADS_REFRESH_TOKEN

—

для авто-обновления токена (refresh)

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

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

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

Инструмент

Метод

Описание

list_campaigns

GET /ad_plans.json

Кампании (ad_plans), фильтр по статусу, авто-пагинация

create_campaign

POST /ad_plans.json

Создать кампанию: name, objective, budget_limit, budget_limit_day

update_campaign

POST /ad_plans/{id}.json

Обновить: name/бюджет/action (activate/stop/delete)

list_ad_groups

GET /ad_groups.json

Группы объявлений с таргетингом (delivery), фильтр по кампаниям

list_ads

GET /banners.json

Объявления (banners), фильтр по группам, авто-пагинация

create_ad

POST /banners.json

Создать объявление: ad_group_id, textblocks, urls, content

get_statistics

GET /statistics/{type}/{period}.json

Показы (shows), клики, расход; period = day/summary

get_account

GET /user.json

Кабинет и баланс (нужен scope read_payments)

Все инструменты используют 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


Telegram: @vhodvai

Available Tools

8 tools
create_adB

Создать объявление VK Ads: формат, заголовок, описание, ссылка.

Inputs: campaign_id (required), ad_group_id, format, title, +2 more.

create_campaignB

Создать рекламную кампанию VK Ads: название, тип, бюджет.

Inputs: account_id (required), name (required), type, budget.

get_budgetB

Бюджет рекламного кабинета VK Ads: остаток, лимиты.

Inputs: account_id (required).

get_statisticsA

Статистика VK Ads: показы, клики, расход за период по кампаниям/объявлениям.

Inputs: account_id (required), ids (required), date_from (required), date_to (required), +2 more.

list_adsC

Объявления VK Ads по кампаниям: формат, статус, данные.

Inputs: campaign_ids (required).

list_campaignsA

Список рекламных кампаний VK Ads по кабинету с фильтрацией по статусу.

Inputs: account_id (required), status.

list_targeting_groupsC

Группы таргетинга кампании VK Ads.

Inputs: campaign_id (required).

update_campaignB

Обновить кампанию VK Ads: название, бюджет, статус (start/stop).

Inputs: campaign_id (required), name, budget, status.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a distinct action and resource (ad, campaign, budget, statistics, targeting groups), with no ambiguity between them.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (e.g., create_ad, list_campaigns), making them predictable and easy to understand.

    Tool Count5/5

    8 tools is well-scoped for managing VK Ads, covering creation, listing, updates, statistics, and budget without being excessive or insufficient.

    Completeness3/5

    Missing delete operations for both ads and campaigns, no update for ads, and no individual get endpoints, which leaves notable gaps in lifecycle coverage.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Read-only MCP server for analyzing VK Ads campaigns, listing ad structures, retrieving statistics, and generating optimization recommendations.
      8
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Python MCP server that exposes Meta Marketing API data, providing tools to manage ad accounts, campaigns, and analytics through natural language interfaces.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP server for VK Ads API: manage ad plans, ad groups, banners, and statistics.
      23
      196 npm
      13
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      MCP server for VK Ads API (myTarget v2) that allows AI agents to manage advertising accounts: create and modify campaigns, ads, upload creatives, and fetch statistics.
      145 npm
      6
      Apache 2.0