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

---

Терминология 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.