<p align="center">
  <img src="docs/img/cover.png" alt="VK Ads MCP: аналитика и управление рекламой" width="100%">
</p>

<h1 align="center">VK Ads MCP All in One</h1>

<p align="center"><strong>Бесплатный MCP-сервер для полноценной настройки, анализа и ведения рекламы во VK с помощью ИИ.</strong></p>

<p align="center">
  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-22%2B-339933?logo=nodedotjs&logoColor=white" alt="Node.js 22+"></a>
  <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-stdio-1f6feb" alt="MCP stdio"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0b8f60" alt="Лицензия MIT"></a>
  <img src="https://img.shields.io/badge/version-0.1.350-2563eb" alt="Версия 0.1.350">
</p>

`VK Ads MCP All in One` можно подключить к любому ИИ-агенту с поддержкой MCP. В диалоге с агентом можно анализировать эффективность рекламы, получать рекомендации по её улучшению, искать и создавать аудитории, загружать креативы, создавать кампании, группы и объявления и управлять ими на основе актуальных данных кабинета.

Сервер работает с официальным VK Ads API: читает кампании, группы и объявления, получает статистику, управляет аудиториями, креативами, лид-формами, опросами, подписками, прайс-листами и справочниками. Отдельный блок Core VK API ищет и анализирует публичные сообщества. Перед рекламным исследованием сервер требует описание покупателя и отдельное решение по конкурентам, затем разделяет целевые, смежные, партнёрские и конкурентные сообщества, а также сообщества поставщиков.

[Инструкция по поиску и оценке сообществ](docs/community-search-guide.md) показывает авторизацию, обязательный рекламный бриф, баллы, статусы и фактический пример детской футбольной секции в Домодедове. К примеру приложены отдельные [рекомендации и ручная проверка](docs/community-search-football-recommended.md), а также [отчёт об отклонённых сообществах](docs/community-search-football-rejected.md).

В текущей версии зарегистрировано 136 инструментов. Из них 122 прошли проверку реальными вызовами, ещё 14 пока недоступны или не проверены. Все 10 инструментов исследования сообществ VK и семь инструментов для аудиторий подписчиков доступны для обычной работы.

> [!IMPORTANT]
> Создание, изменение и удаление объектов, а также загрузка, отправка и экспорт данных выполняются только после вашего явного запроса. Перед изменением сервер проверяет действие и актуальное состояние кабинета через `vk_ads_action_prepare`; запись начинается только при `ready: true`.

## Быстрый старт

> [!TIP]
> Установка выполняется одной командой. Установщик скачает сервер, запросит данные VK Ads, подключит выбранные MCP-клиенты и установит навык для работы с VK Рекламой в каждый из них.

### 1. Подготовьте данные

<table width="100%">
  <thead>
    <tr>
      <th width="30%">Потребуется</th>
      <th width="70%">Условие</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Node.js</td>
      <td><a href="https://nodejs.org/en/download">Установите Node.js версии 22 или новее по официальной инструкции</a>. npm устанавливается вместе с Node.js</td>
    </tr>
    <tr>
      <td>VK Реклама</td>
      <td>Откройте <a href="https://ads.vk.ru/hq/settings">настройки личного кабинета VK Рекламы</a>. Внизу страницы, в разделе «Получить API-доступ», выдаются <code>client_id</code> и <code>client_secret</code></td>
    </tr>
  </tbody>
</table>

### 2. Запустите установщик

```bash
npx --yes github:sergeylopukhov/vk-ads-mcp-all-in-one
```

<details>
<summary><strong>Что сделает установщик</strong></summary>

1. Скачает последнюю версию, установит зависимости и соберёт сервер.
2. Запросит `client_id` и `client_secret`. Секрет вводится в скрытом режиме.
3. Предложит подключить поиск сообществ через отдельный OAuth VK.
4. Сохранит учётные данные и токены в локальном `auth.env`.
5. Найдёт установленные MCP-клиенты и покажет список с галочками. Стрелки перемещают курсор, пробел снимает или ставит галочку, Enter подтверждает выбор.
6. Подключит сервер под именем `vk-ads`.
7. Установит навык для работы с VK Рекламой во все выбранные клиенты.

</details>

> [!NOTE]
> Поддерживаются OpenCode, OpenClaw, Hermes Agent, Codex CLI, Claude Code, Gemini CLI, Qwen Code, Kimi Code CLI и Cursor. По умолчанию выбраны все найденные клиенты. Для продолжения нужен хотя бы один. Чтобы установить сервер без подключения к клиенту, используйте `--no-register`.

<details>
<summary><strong>Что устанавливается вместе с MCP</strong></summary>

Универсальный Agent Skill устанавливается для каждого выбранного клиента и автоматически включается в задачах о VK Ads и сообществах VK. Он выбирает подходящие инструменты MCP, помогает восстанавливать токены, проверять подключение, анализировать статистику и сообщества, управлять кампаниями, аудиториями, лидами и опросами. Навык запускает инструменты записи только после вашего явного запроса. Навык и его справочники обновляются вместе с сервером.

Если перед поиском сообществ нужно собрать подробный бриф, навык предлагает ответить в чате или установить отдельный [интерактивный опросник](https://github.com/sergeylopukhov/interactive-project-questionnaire). Опросник устанавливается только с вашего согласия. Его установщик поддерживает OpenCode, Claude Code, Codex, Cursor, Gemini CLI, Qwen Code, Kimi Code CLI, Hermes Agent и другие клиенты формата Agent Skills.

</details>

### 3. Проверьте подключение

Перезапустите выбранные клиенты и отправьте:

```text
Проверь подключение к VK Рекламе и покажи доступные кампании. Ничего не меняй.
```

## Обновление

> [!TIP]
> Для обновления повторно выполните команду установки. Установщик покажет установленную и доступную версии.

```bash
npx --yes github:sergeylopukhov/vk-ads-mcp-all-in-one
```

<table width="100%">
  <thead>
    <tr>
      <th width="30%">Действие</th>
      <th width="70%">Результат</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Обновить</td>
      <td>Установщик снова покажет список найденных клиентов. Ранее настроенные клиенты будут отмечены, остальные можно выбрать дополнительно. <code>auth.env</code>, токены и локальный аудит сохранятся</td>
    </tr>
    <tr>
      <td>Установить заново</td>
      <td>Установщик снова предложит выбрать клиенты, запросит <code>client_id</code> и <code>client_secret</code>, а сохранённые токены будут удалены</td>
    </tr>
  </tbody>
</table>

<details>
<summary><strong>Каталоги установки</strong></summary>

<table width="100%">
  <thead>
    <tr>
      <th width="30%">Система</th>
      <th width="70%">Каталог по умолчанию</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>macOS</td>
      <td><code>~/Library/Application Support/VK Ads MCP</code></td>
    </tr>
    <tr>
      <td>Linux</td>
      <td><code>~/.local/share/vk-ads-mcp</code></td>
    </tr>
    <tr>
      <td>Windows</td>
      <td><code>%LOCALAPPDATA%\VK Ads MCP</code></td>
    </tr>
  </tbody>
</table>

</details>

<details>
<summary><strong>Дополнительные параметры установки</strong></summary>

Для другой папки или ветки:

```bash
npx --yes github:sergeylopukhov/vk-ads-mcp-all-in-one --install-dir "/полный/путь" --ref main
```

Для установки без интерактивного выбора:

```bash
npx --yes github:sergeylopukhov/vk-ads-mcp-all-in-one --clients codex,openclaw,hermes
```

Параметр `--all-detected` подключает все найденные клиенты, а `--no-register` пропускает их настройку.

Все параметры:

```bash
npx --yes github:sergeylopukhov/vk-ads-mcp-all-in-one --help
```

</details>

## Как создаётся и хранится токен

> [!NOTE]
> Учётные данные и токены хранятся только в локальном `auth.env` внутри каталога установки. Токен с истекающим сроком действия обновляется автоматически.

<details>
<summary><strong>Содержимое auth.env</strong></summary>

```dotenv
VK_ADS_CLIENT_ID=
VK_ADS_CLIENT_SECRET=
VK_ADS_TOKEN=
VK_ADS_REFRESH_TOKEN=
VK_ADS_TOKEN_EXPIRES_AT=
VK_API_TOKEN=
VK_API_TOKEN_TYPE=vk_id
VK_API_CLIENT_ID=
VK_API_DEVICE_ID=
VK_API_REFRESH_TOKEN=
VK_API_TOKEN_EXPIRES_AT=
VK_COMMUNITY_RESEARCH_TTL_DAYS=30
```

</details>

Чтобы отключить автоматическое удаление результатов исследований, установите
`VK_COMMUNITY_RESEARCH_TTL_DAYS=0`. В этом режиме сервер не использует
сохранённый анализ как кэш: новые поиски получают актуальные данные VK.

<details>
<summary><strong>Получение и обновление токена VK Ads</strong></summary>

При первом запросе сервер получает токен по `client_id` и `client_secret`. Если VK Ads возвращает `refresh_token`, сервер сохраняет его и заранее обновляет токен доступа.

Токен с истекающим сроком действия обновляется автоматически. После HTTP `401` сервер один раз обновляет отклонённую пару и повторяет запрос. Для ручного обновления используется `vk_ads_oauth_token_refresh`. Если пара полностью отозвана на другом компьютере и обновить её невозможно, `vk_ads_oauth_current_tokens_delete` удаляет все токены настроенного аккаунта, очищает локальные значения и запрашивает новую пару.

</details>

<details>
<summary><strong>Токен для сообществ VK</strong></summary>

Инструменты сообществ используют отдельный `VK_API_TOKEN`. По умолчанию установщик предлагает режим OAuth `legacy` через встроенное приложение VK с `client_id=6270012`: достаточно нажать Enter. Для VK ID укажите своё приложение. Также можно сохранить `VK_API_CLIENT_ID`, `VK_API_DEVICE_ID`, `VK_API_REFRESH_TOKEN` и срок действия, чтобы сервер обновлял токен Core VK при запуске.

</details>

<details>
<summary><strong>Хранение и защита данных</strong></summary>

`auth.env` исключён из Git и npm-пакета. На macOS и Linux установщик создаёт его с правами `0600`. Токены, `client_secret` и полные приватные ответы VK Ads не выводятся через MCP.

</details>

## Что умеет сервер

<table width="100%">
  <thead>
    <tr>
      <th width="25%">Раздел</th>
      <th width="75%">Возможности</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Реклама</td>
      <td>Кампании, группы, объявления, массовые действия и перемодерация</td>
    </tr>
    <tr>
      <td>Креативы</td>
      <td>Загрузка изображений, видео и HTML5 ZIP</td>
    </tr>
    <tr>
      <td>Статистика</td>
      <td>Дневные, итоговые, быстрые, целевые, in-app и офлайн-метрики</td>
    </tr>
    <tr>
      <td>Аудитории</td>
      <td>Счётчики, цели, списки, сегменты, связи и ключи доступа</td>
    </tr>
    <tr>
      <td>Лиды и опросы</td>
      <td>Формы, логотипы, тестовые лиды, архивирование и приватный экспорт</td>
    </tr>
    <tr>
      <td>Данные</td>
      <td>Прайс-листы, подписки, локальная география, URL и справочники</td>
    </tr>
    <tr>
      <td>Кабинет</td>
      <td>Профиль, язык, приложения и безопасные статусы ОРД</td>
    </tr>
    <tr>
      <td>Сообщества VK</td>
      <td>Поиск, обязательный рекламный бриф, классификация отношений с аудиторией, анализ публичных записей, фоновые исследования и экспорт</td>
    </tr>
  </tbody>
</table>

> [!NOTE]
> Полный перечень инструментов, тип доступа и статусы приведены в [каталоге инструментов](docs/tools.md).

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

> [!IMPORTANT]
> Записывающие инструменты используют строгие входные схемы, проверяют актуальное состояние объекта и по возможности читают его повторно после изменения.

<details>
<summary><strong>Как подтверждается изменение</strong></summary>

Записывающие инструменты используют фиксированные API-маршруты и строгие входные схемы. `vk_ads_action_prepare` позволяет заранее проверить действие без изменений в кабинете. Он возвращает `ready`, списки недостающих и несовместимых условий, предупреждения, допустимые значения и безопасный `requestDraft`.

Если подготовка возвращает `requiresConfirmation=true`, вы увидите предложенное исправление `suggestedPatch`. Связанный объект изменится только после вашего отдельного согласия. При `ready=true` MCP-клиент выполнит одну подготовленную операцию с теми же данными.

Для операций над существующим объектом сервер читает актуальное состояние непосредственно перед записью. После изменения он повторно читает объект или коллекцию, когда VK Ads предоставляет подходящий контракт.

Успешный HTTP-ответ не считается доказательством изменения. Если контрольное чтение не подтвердило результат, MCP возвращает ошибку или неподтверждённый итог. Например, `remoderated=false` не превращается в успешную перемодерацию.

</details>

<details>
<summary><strong>Пример подготовки и записи</strong></summary>

Для проверки изменения языка MCP-клиент сначала передаёт в `vk_ads_action_prepare` имя действия и его входные данные:

```json
{
  "action": "user.language_update",
  "input": {
    "version": "v3",
    "language": "en"
  }
}
```

При `ready=true` MCP-клиент передаёт те же поля в `vk_ads_user_language_update`:

```json
{
  "version": "v3",
  "language": "en"
}
```

Если английский язык уже установлен, подготовка вернёт `ready=false`, `stage="compatibility"` и код `user_language_noop`. Запись в этом случае не выполняется.

</details>

<details>
<summary><strong>Что хранится в локальном журнале</strong></summary>

Журнал операций хранится локально в `.vk-ads-audit.jsonl`. В нём нет токенов, содержимого запросов, идентификаторов кампаний, названий или ответов VK Ads.

</details>

## Диагностика ошибок VK

Если VK отклоняет запрос, MCP возвращает код ошибки, безопасное сообщение провайдера и пути к полям с ошибками. Например, вместо одного `validation_failed` будет указано поле `content.image_1080x607` и причина отказа, если VK передал эти сведения.

Из диагностики удаляются токены, секреты, пароли, адреса страниц, электронная почта и исходные строки загруженных файлов. Сервер обрабатывает ошибки одинаково для инструментов VK Ads, авторизации, поиска сообществ и обновления токена VK ID.

## MCP-клиенты

> [!NOTE]
> Установщик находит OpenCode, OpenClaw, Hermes Agent, Codex CLI, Claude Code, Gemini CLI, Qwen Code, Kimi Code CLI и Cursor, затем предлагает выбрать нужные клиенты.

<table width="100%">
  <thead>
    <tr>
      <th width="30%">Клиент</th>
      <th width="70%">Инструкция</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Codex</td>
      <td><a href="docs/setup-codex.md">Установка и проверка подключения</a></td>
    </tr>
    <tr>
      <td>OpenCode, OpenClaw, Hermes Agent, Claude Code, Gemini CLI, Qwen Code, Kimi Code CLI и Cursor</td>
      <td><a href="docs/setup-clients.md">Команды подключения и пути к конфигурациям</a></td>
    </tr>
  </tbody>
</table>

## Документация

<table width="100%">
  <thead>
    <tr>
      <th width="40%">Документ</th>
      <th width="60%">Содержание</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><a href="docs/community-search-guide.md">Поиск и оценка сообществ VK</a></td>
      <td>Авторизация, рекламный бриф, режимы, баллы, статусы и фактический пример поиска</td>
    </tr>
    <tr>
      <td><a href="docs/community-search-football-recommended.md">Рекомендации и ручная проверка</a></td>
      <td>Фактические результаты для детской футбольной секции в Домодедове</td>
    </tr>
    <tr>
      <td><a href="docs/community-search-football-rejected.md">Отклонённые сообщества</a></td>
      <td>Показательные причины отклонения из того же исследования</td>
    </tr>
    <tr>
      <td><a href="docs/tools.md">Каталог инструментов</a></td>
      <td>Названия, назначение, тип доступа и статус каждого инструмента</td>
    </tr>
    <tr>
      <td><a href="docs/setup-codex.md">Подключение Codex</a></td>
      <td>Установка, запуск и проверка подключения</td>
    </tr>
    <tr>
      <td><a href="docs/setup-clients.md">Подключение MCP-клиентов</a></td>
      <td>Настройка OpenCode, OpenClaw, Hermes Agent, Claude Code, Gemini CLI, Qwen Code, Kimi Code CLI и Cursor</td>
    </tr>
    <tr>
      <td><a href="docs/SECURITY.md">Политика безопасности</a></td>
      <td>Хранение данных, токены и безопасность записывающих операций</td>
    </tr>
    <tr>
      <td><a href="docs/CHANGELOG.md">История изменений</a></td>
      <td>Пользовательские изменения по версиям</td>
    </tr>
    <tr>
      <td><a href="LICENSE">Лицензия MIT</a></td>
      <td>Условия использования и распространения</td>
    </tr>
  </tbody>
</table>