Skip to main content
Glama
vk-ads-mcp

vk-ads-mcp

vk-ads-mcp

Hardened fork of lexamarketolog/vk-ads-mcp. Управляет рекламными кампаниями в VK Реклама (myTarget API v2) через любой MCP-клиент — Claude Code, Claude Desktop, Cursor и другие. По умолчанию работает только на чтение; мутирующие операции включаются явно через VK_ADS_ENABLE_WRITES=true. Каждый партнёр использует собственные API-ключи.


Возможности

Чтение (24 инструмента, всегда доступны)

Позволяют просматривать данные аккаунта, не изменяя ничего в кабинете.

auth_check, get_account_info, list_ad_plans, get_ad_plan, list_campaigns, get_campaign, list_ad_groups, get_ad_group, list_banners, get_banner, get_statistics_day, get_statistics_summary, get_statistics_breakdown, get_async_report, list_remarketing_groups, list_remarketing_pixels, get_lookalike, list_users_lists, list_content, list_feeds, list_agency_clients, list_packages, search_regions, get_dictionary

Управление (31 инструмент, только при VK_ADS_ENABLE_WRITES=true)

Мутирующие операции — создание, изменение, удаление объектов, загрузка файлов. Требуют явного включения, так как затрагивают бюджет и данные кампаний.

create_ad_plan, update_ad_plan, delete_ad_plan, create_campaign, update_campaign, set_campaign_status, delete_campaign, create_ad_group, update_ad_group, delete_ad_group, create_banner, update_banner, moderate_banner, delete_banner, upload_image, upload_video, create_remarketing_group, update_remarketing_group, delete_remarketing_group, create_remarketing_pixel, delete_remarketing_pixel, create_lookalike, create_users_list, upload_users_list_items, delete_users_list, create_feed, update_feed, delete_feed, create_agency_client, create_async_report, revoke_token


Related MCP server: meta-ads-mcp

Терминология VK Ads API (важно)

API использует устаревшие имена myTarget. В новом кабинете ads.vk.com:

Интерфейс кабинета

Имя в API

MCP-инструменты

Кампания (верхний уровень)

ad_plan

list_ad_plans, create_ad_plan, ...

Группа объявлений

campaign

list_campaigns, create_campaign, ...

Объявление

banner

list_banners, create_banner, ...

Внимание: campaign без ad_plan_id создаётся без ошибки, но становится «сиротой» и не отображается в новом кабинете. Всегда привязывайте кампанию к плану.


Установка

Claude Code

claude mcp add vk-ads \
  --env VK_ADS_CLIENT_ID=<id> \
  --env VK_ADS_CLIENT_SECRET=<secret> \
  -- uvx --from git+https://github.com/nikolaymokh-dev/vk-ads-mcp@v0.1.0 vk-ads-mcp

.claude.json / Cursor / другие MCP-клиенты

{
  "mcpServers": {
    "vk-ads": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/nikolaymokh-dev/vk-ads-mcp@v0.1.0",
        "vk-ads-mcp"
      ],
      "env": {
        "VK_ADS_CLIENT_ID": "<id>",
        "VK_ADS_CLIENT_SECRET": "<secret>"
      }
    }
  }
}

Вместо client_id/client_secret можно передать готовый токен:

"env": {
  "VK_ADS_ACCESS_TOKEN": "<token>"
}

Включение управления кампаниями

Добавьте переменную окружения VK_ADS_ENABLE_WRITES=true при запуске сервера:

claude mcp add vk-ads \
  --env VK_ADS_CLIENT_ID=<id> \
  --env VK_ADS_CLIENT_SECRET=<secret> \
  --env VK_ADS_ENABLE_WRITES=true \
  -- uvx --from git+https://github.com/nikolaymokh-dev/vk-ads-mcp@v0.1.0 vk-ads-mcp

Или в JSON-конфиге:

"env": {
  "VK_ADS_CLIENT_ID": "<id>",
  "VK_ADS_CLIENT_SECRET": "<secret>",
  "VK_ADS_ENABLE_WRITES": "true"
}

Внимание: мутирующие инструменты могут создавать объекты, менять статусы и тратить рекламный бюджет. Включайте только там, где это действительно нужно.


Настройка доступа

Как получить API-ключи в кабинете VK Реклама: docs/SETUP.md.

Безопасность

Что защищает этот форк и какие ограничения остаются: docs/SECURITY.md.


Отличия от оригинала (что добавил форк)

Этот форк добавляет слой безопасности поверх lexamarketolog/vk-ads-mcp, не меняя поведение самих инструментов:

  • Read-only по умолчанию — 31 мутирующий инструмент скрыт, пока не задан VK_ADS_ENABLE_WRITES=true.

  • Защита upload от SSRF — блок непубличных адресов (loopback/RFC1918/link-local 169.254.169.254/CGNAT) + follow_redirects=False.

  • Запрет чтения произвольных файлов — локальный upload только из VK_ADS_ALLOW_LOCAL_UPLOAD=<dir> (с проверкой path-traversal).

  • Lock base_url на ads.vk.com (override через VK_ADS_ALLOW_BASE_URL_OVERRIDE).

  • Защита от path-traversal в пользовательских значениях, попадающих в URL-путь.

  • Воспроизводимая установка через uvx по тегу, запинённый uv.lock, CI, тесты безопасности.

Полный список — в CHANGELOG.md; модель угроз — в docs/SECURITY.md.


Лицензия

MIT — форк lexamarketolog/vk-ads-mcp, см. NOTICE.

Available Tools

24 tools
auth_checkA

Verify credentials and API reachability.

Returns current user info if token is valid, otherwise an error payload.

Inputs: no named parameters. Returns: object

get_account_infoA

Get current account info (including balance/budget fields).

Inputs: no named parameters. Returns: object

get_ad_groupC

Get a single ad group by ID.

Inputs: ad_group_id (required), fields. Returns: object

get_ad_planB

Get a single ad plan by ID.

Inputs: ad_plan_id (required), fields. Returns: object

get_async_reportC

Get async report status or download link when ready.

Inputs: report_id (required). Returns: object

get_bannerB

Get a single banner by ID.

Inputs: banner_id (required), fields. Returns: object

get_campaignC

Get a single campaign by ID.

Inputs: campaign_id (required), fields. Returns: object

get_dictionaryA

Fetch an arbitrary VK Ads dictionary.

Examples:

  • name="interests" → /api/v2/interests.json

  • name="browsers" → /api/v2/browsers.json

  • name="currencies" → /api/v2/currencies.json

  • name="sectors" → /api/v2/sectors.json

Inputs: name (required), params. Returns: object

get_lookalikeB

Get a lookalike audience (incl. processing status).

Inputs: lookalike_id (required). Returns: object

get_statistics_breakdownC

Statistics sliced by a dimension.

Args: entity: campaigns | ad_groups | banners. ids: comma-separated IDs. group_by: one of age, gender, region, placement, os, device_type. metrics: metric group.

Inputs: entity (required), ids (required), date_from (required), date_to (required), +2 more. Returns: object

get_statistics_dayB

Daily statistics.

Args: entity: one of campaigns, ad_groups, banners, users. ids: comma-separated entity IDs (e.g. "123,456"). date_from: YYYY-MM-DD. date_to: YYYY-MM-DD. metrics: optional metric group (e.g. base, video, uniques, all).

Inputs: entity (required), ids (required), date_from (required), date_to (required), +1 more. Returns: object

get_statistics_summaryC

Summary (aggregated) statistics for the period.

Args mirror get_statistics_day.

Inputs: entity (required), ids (required), date_from, date_to, +1 more. Returns: object

list_ad_groupsB

List ad groups, optionally filtered by campaign_id.

Inputs: campaign_id, limit, offset, fields. Returns: object

list_ad_plansC

List ad plans (top-level entity visible as "Кампания" in VK Ads UI).

Inputs: limit, offset, fields. Returns: object

list_agency_clientsC

List clients managed under an agency account.

Inputs: limit, offset. Returns: object

list_bannersC

List banners (individual ads).

Inputs: campaign_id, ad_group_id, limit, offset, +1 more. Returns: object

list_campaignsA

List advertising campaigns.

Args: limit: max items (default 50, max 250). offset: pagination offset. status: filter by status (active, blocked, deleted, etc.). fields: comma-separated field list to return.

Inputs: limit, offset, status, fields. Returns: object

list_contentB

List uploaded content.

Args: content_type: one of static, video, html5. limit, offset: pagination.

Inputs: content_type, limit, offset. Returns: object

list_feedsC

List product feeds for dynamic/shopping ads.

Inputs: limit, offset. Returns: object

list_packagesA

List available ad packages (ad formats / placements).

Inputs: no named parameters. Returns: object

list_remarketing_groupsC

List remarketing audiences.

Inputs: limit, offset. Returns: object

list_remarketing_pixelsC

List remarketing pixels (tracking tags).

Inputs: limit, offset. Returns: object

list_users_listsB

List custom-audience users lists (uploaded phone/email hash segments).

Inputs: limit, offset. Returns: object

search_regionsC

Search geo regions for targeting (cities, regions).

Inputs: query (required), limit. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 24 tools

    Disambiguation5/5

    Each tool targets a distinct entity or action (authentication, specific entities like campaign/ad group, statistics variants, different list operations). No two tools overlap in function; get/list pairs are complementary. The three statistics tools are differentiated by aggregation level (breakdown, daily, summary).

    Naming Consistency5/5

    All tool names follow a consistent snake_case pattern with clear verb prefixes: 'get_' for single entities, 'list_' for plural entities, 'search_' for search, 'auth_' for authentication. No mixing of conventions or unclear verbs.

    Tool Count5/5

    24 tools cover a broad range of VK Ads operations (auth, account, campaigns, ad groups, banners, ads, statistics, dictionaries, remarketing, content, feeds, packages, regions). The count is well-scoped for a comprehensive ads management server, neither too sparse nor bloated.

    Completeness2/5

    The tool surface is entirely read-only: only get, list, search, and statistics tools exist. There are no create, update, or delete operations for any entity (campaigns, ad groups, banners, etc.), which severely limits practical use for campaign management. Critical mutation capabilities are missing.

    Maintenance

    ActivityInactive
    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
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables read-only Meta Ads reporting and diagnostics, plus safe, preview-before-apply mutations such as campaign creation, duplication, targeting replacement, and attribution changes.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables MCP clients such as Claude to read Google Ads performance reports, run keyword planner queries, and create or manage search and Performance Max campaigns, ad groups, keywords, ads, budgets, and delivery status. Write operations default to paused and can be disabled entirely for read-only analytics use.
      16
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables MCP clients to read Snapchat Ads campaigns and performance and to prepare preview-first changes for selected ad accounts, with opt-in write tools and explicit confirmation before applying updates.
      21
      131 npm
      Apache 2.0