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

v0.3.0

Published

16 days ago

MCP server for VK Ads API (ads.vk.com, myTarget v2) — Bun/TypeScript port

0High
0Medium
0Low

dmitry-zhokhov

akainq

mcp model-context-protocol vk-ads ppc advertising click-ru bun

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

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

Что это

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

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

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

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

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

Инструменты

| Область | Что позволяет сделать | |---|---| | Авторизация и аккаунт | Проверить доступ, получить данные аккаунта и отозвать лишние OAuth-токены | | Кампании — API ad_plans | Создавать и вести кампании верхнего уровня, задавать сроки и ограничения бюджета | | Группы объявлений — API campaigns | Создавать группы с целью, бюджетом и таргетингом, запускать и останавливать показы | | Дополнительные группы — API ad_groups | Группировать объявления по таргетингу | | Объявления — API banners | Создавать и править объявления, привязывать креативы и отправлять на модерацию | | Контент | Загружать изображения и видео из локального файла или по URL | | Статистика | Получать данные по дням, итоги за период, срезы и большие асинхронные отчёты | | Ремаркетинг | Работать с сегментами, пикселями и списками пользователей | | Агентство | Получать список клиентов и создавать клиентов агентского аккаунта | | Справочники | Искать регионы, пакеты форматов, интересы, браузеры, валюты и отрасли |

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

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

| В интерфейсе | В API | |---|---| | Кампания | ad_plan | | Группа объявлений | campaign | | Объявление | banner |

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

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

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

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

Человек:

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

У сервера нет встроенной точки подтверждения: вызов на изменение уходит в API сразу. Кампании, группы и объявления удаляются мягко через статус deleted; удаление сегментов, пикселей и списков пользователей необратимо на стороне 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 рекламного аккаунта VK Рекламы в 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 аккаунта VK Рекламы — через 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), кэширует на диске и обновляет при 401. При ошибке token_limit_exceeded (у VK лимит ≤5 активных токенов) используйте инструмент 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 аккаунта VK Рекламы>"
      }
    }
  }
}

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

📋 Инструкция для AI-агента — скопируйте и передайте своему агенту (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).

| Метод + путь | Назначение | |---|---| | POST /mcp | JSON-RPC 2.0 запрос (или батч) | | GET /healthz | health check | | GET /mcp/tools | список инструментов (отладка) |

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

X-VK-Ads-Token: <access_token>       X-Click-Ru-Token: <API-токен>
                                     X-Click-Ru-Account-Id: <ID аккаунта VK Рекламы>
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) чужой токен из кэша не выдаёт.

⚠️ Безопасность: при публикации в сеть задайте 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