# vk-ads-mcp

Hardened fork of [lexamarketolog/vk-ads-mcp](https://github.com/lexamarketolog/vk-ads-mcp). Управляет рекламными кампаниями в [VK Реклама](https://ads.vk.com) (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

```sh
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-клиенты

```json
{
  "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` можно передать готовый токен:

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

---

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

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

```sh
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-конфиге:

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

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

---

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

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

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

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

---

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

Этот форк добавляет слой безопасности поверх [lexamarketolog/vk-ads-mcp](https://github.com/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](CHANGELOG.md); модель угроз — в [docs/SECURITY.md](docs/SECURITY.md).

---

## Лицензия

MIT — форк [lexamarketolog/vk-ads-mcp](https://github.com/lexamarketolog/vk-ads-mcp), см. [NOTICE](NOTICE).