MCP «ВК Реклама»

MCP на Bun и TypeScript, который даёт ИИ-агенту прямой доступ к API ВК Рекламы (myTarget API v2).

Что это

Из диалога с вами агент читает состояние аккаунта и вносит изменения через API: смотрит кампании, группы и объявления, выгружает статистику со срезами, создаёт и правит сущности, загружает креативы, собирает аудитории для ремаркетинга, запускает и останавливает показы.

Стратегию и тексты объявлений сервер не придумывает — он исполняет решения, которые принимаете вы вместе с агентом. В наборе 44 инструмента.

Как проходит работа

1. Подключение и доступ. Вы выбираете готовый токен ВК Рекламы, OAuth-приложение или подключение через click.ru. Проверить связь можно инструментом auth_check. Сервер работает локально через стандартный ввод-вывод или по HTTP, в том числе с несколькими аккаунтами.
2. Чтение состояния. Перед изменением агент получает кампании, группы, объявления, справочники и текущую статистику.
3. Изменение. Агент создаёт и правит сущности, загружает изображения и видео, собирает аудитории и списки клиентов и меняет статусы.
4. Проверка. После изменения агент снова читает состояние и статистику.

Сервер не запускает кампании самостоятельно. Показ включается только отдельной явной сменой статуса.

Инструменты

Терминология API

В новом интерфейсе ВК Рекламы и API одни и те же уровни называются по-разному:

Группа campaign, созданная без ad_plan_id, становится «сиротой» и не видна в новом кабинете. Создавайте группы внутри кампании или сразу передавайте ad_plan_id.

Что делает агент, а что остаётся человеку

Сервер и агент:

• получают и обновляют токен доступа;
• читают состояние аккаунта и справочники;
• создают, правят и загружают сущности по вашему заданию;
• получают статистику и проверяют результат изменения.

Человек:

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

У сервера нет встроенной точки подтверждения: вызов на изменение уходит в API сразу. Кампании, группы и объявления удаляются мягко через статус deleted; удаление сегментов, пикселей и списков пользователей необратимо на стороне API.

Ограничения

• Сервер не пишет стратегию и не придумывает креативы.
• Объявления нельзя создать отдельным вызовом: в API нет такого метода, они заводятся вложенным массивом banners внутри группы объявлений. Отправки на модерацию в API тоже нет.
• Асинхронных отчётов в API нет — доступны обычная статистика по дням, итоги и срезы.
• Из справочников доступны валюты, страны и регионы; интересов, отраслей и браузеров в API нет.
• В наборе нет инструментов для создания лид-форм.
• API не позволяет получить список ранее загруженных изображений и видео.
• Похожие аудитории и группы ремаркетинга недоступны; используйте сегменты, пиксели и списки пользователей.
• Сервер не гарантирует прохождение модерации.
• ВК ограничивает число активных OAuth-токенов: при превышении лишние токены нужно отозвать.
• Операции чтения проверялись на живом API выборочно. Создание, правка и удаление покрыты автоматическими тестами, но перед работой с важным аккаунтом их стоит проверить на безопасном объекте.

Требования

• Bun 1.1+

Установка

Из npm — одной командой (нужен установленный Bun):

bunx @ai-hub-open/vk-ads-mcp

Для подключения в конфиге MCP-клиента: "command": "bunx", "args": ["@ai-hub-open/vk-ads-mcp"] плюс переменные окружения одного из режимов ниже.

Или из исходников:

git clone https://github.com/ai-hub-open/vk-ads-mcp.git
cd vk-ads-mcp
bun install

Настройка

Скопируйте .env.example в .env и заполните один из вариантов (переменные окружения имеют приоритет над .env):

A. Через click.ru — основной путь: токен без заявок на доступ к API, свои ключи ВК не нужны:

CLICK_RU_TOKEN=<API-токен из профиля click.ru>
CLICK_RU_ACCOUNT_ID=<ID рекламного аккаунта ВК Рекламы в click.ru>
CLICK_RU_USER_ID=<ID пользователя click.ru>   # только при работе из мастер-аккаунта

Сервер сам запрашивает access_token VK Ads у click.ru, кэширует и обновляет его при 401. Токен click.ru создаётся в профиле https://click.ru/userinfo.html → поле «API Token» → «Создать»; ID аккаунта ВК Рекламы — через GET /accounts в https://api.click.ru/V0/docs/. Справка: https://help.click.ru/2327, https://help.click.ru/4814.

B. Готовый access_token VK Ads:

VK_ADS_ACCESS_TOKEN=eyJ0...

Токен: ads.vk.com → Настройки профиля → Получить токен / API.

C. OAuth 2.0 Client Credentials — приложение, одобренное на target.vk.ru:

VK_ADS_CLIENT_ID=12345
VK_ADS_CLIENT_SECRET=abcdef...
# VK_ADS_AGENCY_CLIENT_NAME=<username клиента>  # агентство от имени клиента

Сервер сам получает токен (grant_type=client_credentials / agency_client_credentials) и хранит его вместе с refresh_token. Когда срок истекает, токен продлевается, а не выпускается заново: у ВК лимит в 5 активных токенов на приложение и пользователя, и продление заменяет токен, не занимая новый слот. Так подключение живёт сколько угодно, а остальные слоты остаются свободными для ваших других интеграций.

В сетевом режиме подключите том для кэша, иначе refresh_token теряется при каждой выкладке и сервер выпускает новый токен — в docker-compose.yml это уже сделано. Если лимит всё же исчерпан, отзовите лишние токены инструментом vk_ads_token_revoke.

Запуск

bun run src/index.ts          # stdio — для локальных MCP-клиентов
bun run src/index.ts --http   # HTTP-сервер на :3000

Подключение к Claude Code

.mcp.json в корне вашего проекта (см. также .mcp.json.example):

{
  "mcpServers": {
    "vk-ads": {
      "command": "bun",
      "args": ["run", "/абсолютный/путь/к/vk-ads-mcp/src/index.ts"],
      "env": {
        "CLICK_RU_TOKEN": "<ваш токен>",
        "CLICK_RU_ACCOUNT_ID": "<ID аккаунта ВК Рекламы>"
      }
    }
  }
}

Для режима готового токена в env вместо CLICK_RU_* укажите VK_ADS_ACCESS_TOKEN.

📋 Инструкция для ИИ-агента — скопируйте и передайте своему агенту (Claude Code / Codex), подставив ключи:

Установи и подключи MCP «VK Ads»: склонируй https://github.com/ai-hub-open/vk-ads-mcp.git, проверь Bun (bun --version, если нет — установи с https://bun.sh), выполни bun install в корне репозитория. Зарегистрируй локальный stdio-MCP: команда bun, аргументы run <абсолютный_путь_к_репо>/src/index.ts, переменные окружения — мои ключи: CLICK_RU_TOKEN=<...>, CLICK_RU_ACCOUNT_ID=<...> (или VK_ADS_ACCESS_TOKEN=<...> для режима готового токена). Проверь tools/list и сообщи результат.

HTTP-режим

MCP_TRANSPORT=http MCP_PORT=3000 bun run src/index.ts

Переменные: MCP_PORT (3000), MCP_HOST (0.0.0.0), MCP_AUTH_TOKEN (если задан — запросы должны нести Authorization: Bearer <token>), MCP_ALLOWED_ORIGIN (CORS).

Несколько аккаунтов: данные доступа можно передавать в заголовках каждого запроса; они имеют приоритет над .env. Один сервер может обслуживать несколько клиентов:

X-VK-Ads-Token: <access_token>       X-Click-Ru-Token: <API-токен>
                                     X-Click-Ru-Account-Id: <ID аккаунта ВК Рекламы>
X-VK-Ads-Client-Id: <client_id>      X-Click-Ru-User-Id: <ID пользователя>
X-VK-Ads-Client-Secret: <secret>     X-Click-Ru-Base-Url: <опционально>
X-VK-Ads-Agency-Client-Name: <...>   X-VK-Ads-Base-Url: <опционально>

Сервер можно запустить без данных доступа в .env — тогда они передаются в каждом запросе. Полученные через OAuth или click.ru токены сохраняются в памяти и на диске отдельно для каждого набора доступа: ключ хранения включает отпечаток секрета, поэтому знание одного лишь публичного идентификатора (client_id, account_id) чужой токен из кэша не выдаёт.

Данные доступа в адресе — для клиентов без заголовков. Claude Desktop и подобные приложения позволяют указать только URL сервера. Для них включается отдельный набор адресов: MCP_ALLOW_URL_TOKEN=true, после чего подходит любая из трёх форм:

https://ваш-домен/t/<токен ВК Рекламы>                  готовый токен, живёт 24 часа
https://ваш-домен/o/<client_id>/<client_secret>         сервер обновляет токен сам
https://ваш-домен/c/<токен click.ru>/<id аккаунта>      сервер обновляет токен сам

Пользователю достаточно вставить такой адрес в настройки — больше ничего не требуется: ни установки программ, ни отдельного входа. Данные доступа в адресе сами служат пропуском, поэтому MCP_AUTH_TOKEN для них не спрашивается (обычный /mcp продолжает его требовать).

Выбирайте вторую или третью форму, если подключение должно работать дольше суток: готовый токен ВК Рекламы живёт 24 часа, а client_id + client_secret и ключ click.ru долгоживущие — сервер по ним выпускает и обновляет токен сам. Учтите: адрес попадает в журналы обратного прокси-сервера, поэтому отключите в них запись пути и ограничьте частоту запросов.

⚠️ Безопасность: при публикации в сеть задайте MCP_AUTH_TOKEN и закройте порт за обратным прокси-сервером с TLS.

Ограничения загрузки креативов в сетевом режиме. Запросы приходят извне, поэтому чтение файлов с диска сервера выключено, а адреса для загрузки по ссылке проверяются: внутренние диапазоны (127.0.0.1, 169.254.169.254, приватные сети) и уводящие туда перенаправления блокируются. При локальном запуске обе возможности включены — это ваши собственные файлы и сеть. Управление: VK_ADS_ALLOW_LOCAL_FILES, VK_ADS_ALLOW_PRIVATE_NETWORK.

Docker

cp .env.example .env   # заполните ключи и MCP_AUTH_TOKEN
docker compose up -d --build
curl http://localhost:3000/healthz

Тесты

bun test                        # 110 тестов: доступ, хранение токенов, сервер, транспорт, защита от SSRF, инструменты
bun run typecheck               # tsc --noEmit
bun run scripts/live-check.ts   # проверка чтения через реальный API (нужны данные доступа)

Типы и тесты запускаются на каждый pull request и push в main и dev.

Лицензия

Apache License 2.0