MCP server that provides access to the VK Ads API for working with campaigns, audiences, budgets, and stats. It supports authentication via Click.ru token or OAuth, and is designed for use through the Model Context Protocol.

🛠️ Key Features

VK Ads API coverage: campaigns, audiences, budgets, stats
Authentication options: Click.ru token or OAuth

🚀 Use Cases

Manage VK Ads campaigns and their related configurations
Define and update audiences
Track budgets and review advertising performance statistics

⚡ Developer Benefits

Standardized MCP integration for VK Ads API entities (campaigns, audiences, budgets, stats)
Works with either token-based or OAuth-based authentication

⚠️ Limitations

Scope described only for VK Ads API resources: campaigns, audiences, budgets, and stats
Authentication support is limited to Click.ru token or OAuth

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):

bash

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

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

bash

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, свои ключи ВК не нужны:

bash

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:

bash

VK_ADS_ACCESS_TOKEN=eyJ0...

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

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

bash

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.

Запуск

bash

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

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

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

json

{
  "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-режим

bash

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. Один сервер может обслуживать несколько клиентов:

code

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 токены сохраняются в памяти и на диске отдельно для каждого набора доступа.

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

Docker

bash

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

Тесты

bash

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

Лицензия

Apache License 2.0

io.github.ai-hub-open/vk-ads-mcp

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

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

Что это

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

Инструменты

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

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

Ограничения

Требования

Установка

Настройка

Запуск

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

HTTP-режим

Docker

Тесты

Лицензия

Install

Configuration