npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

mcp-vk-ads

v1.8.4

Published

MCP server for the VK Ads (VK Реклама) API — manage ad plans, ad groups, banners and pull statistics from AI agents.

Readme

VK Реклама MCP

npm CI Glama License: MIT

VK Реклама MCP подключает AI-приложение к рекламному кабинету VK Ads. Можно спросить, какие кампании тратят бюджет без результата, сравнить группы и объявления, подготовить новую кампанию или изменить ставку. В отличие от ручного перехода по разделам кабинета, ассистент сопоставляет кампании, статистику, баланс и статусы в одном диалоге.

  • 22 инструмента. Кампании, группы, объявления, статистика, баланс, лимиты API, регионы, подключение кабинета и универсальный запрос к API.
  • Подключение из диалога. Скажите «подключи ВК Рекламу» — сервер объяснит, где взять client_id и client_secret, получит токен и дальше продлевает его сам.
  • Живая реклама. Ставки, бюджеты и расход отображаются в валюте рекламного кабинета — без пересчёта микроединиц.
  • Полная иерархия. Кампания (ad_plan) → группа (ad_group) → объявление (banner).
  • Сначала анализ. Списки, отчёты, баланс и статусы доступны только на чтение.
  • Изменения — в боевом кабинете. Создание, обновление и действия со статусами применяются сразу; у VK Ads нет песочницы.

Начните с безопасного запроса:

Покажи кампании моего аккаунта VK Рекламы и расход за прошлую неделю по группам объявлений.

Подключить сервер · Посмотреть сценарии · Открыть техническую документацию


Увидеть работу за минуту

Содержание

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

Нужен Node.js 20 или новее. Сервер запускается через npx, поэтому отдельно устанавливать пакет не требуется; токен при установке не нужен.

  1. Добавьте сервер в AI-приложение — инструкции для пяти приложений ниже.
  2. Скажите: «Подключи ВК Рекламу» — сервер проведёт подключение прямо в диалоге.
  3. Спросите: «Покажи кампании моего аккаунта VK Рекламы и расход за прошлую неделю по группам объявлений».

Через интерфейс приложения:

  1. Откройте Settings → Plugins → MCP servers.
  2. Нажмите Add server.
  3. Добавьте команду запуска npx -y mcp-vk-ads@latest. Переменные окружения не нужны: кабинет подключается в диалоге.

Через командную строку:

codex mcp add vk-ads -- npx -y mcp-vk-ads@latest

Проверьте подключение:

codex mcp list

Официальная инструкция Codex

claude mcp add \
  --transport stdio \
  --scope user \
  vk-ads \
  -- npx -y mcp-vk-ads@latest

Проверьте сервер:

claude mcp list

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

Откройте Settings → Developer → Edit Config и добавьте сервер в claude_desktop_config.json:

{
  "mcpServers": {
    "vk-ads": {
      "command": "npx",
      "args": ["-y", "mcp-vk-ads@latest"]
    }
  }
}

Если Edit Config недоступна, отредактируйте ~/Library/Application Support/Claude/claude_desktop_config.json на macOS или %APPDATA%\Claude\claude_desktop_config.json на Windows.

Для всех проектов создайте ~/.cursor/mcp.json; только для текущего проекта — .cursor/mcp.json:

{
  "mcpServers": {
    "vk-ads": {
      "command": "npx",
      "args": ["-y", "mcp-vk-ads@latest"]
    }
  }
}

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

Откройте палитру команд и выполните MCP: Open User Configuration. Добавьте в mcp.json:

{
  "servers": {
    "vk-ads": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-vk-ads@latest"]
    }
  }
}

Проверьте запуск командой MCP: List Servers.

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

Что можно поручить

Разобраться с расходом и результатом

  • «Покажи расход, показы, клики и CTR по кампаниям за последние 7 дней».
  • «Какие объявления тратят больше всего и не приносят результата?»
  • «Сравни группы объявлений внутри этой кампании по расходу и кликам».

Понять, почему реклама не показывается

  • «Покажи статус, доставку и модерацию всех объявлений этой группы».
  • «Какие кампании сейчас остановлены?»
  • «Найди объявления, которые не прошли модерацию».

Подготовить изменения в рекламе

  • «Создай текстовую кампанию с дневным бюджетом 5 000 рублей».
  • «Измени дневной бюджет этой группы на 1 500 рублей».
  • «Останови объявление 12345».

Такие команды меняют боевой кабинет. Перед вызовом убедитесь, что ассистент правильно определил кампанию, группу, объявление и сумму.

Найти данные для настройки

  • «Покажи баланс и валюту моего кабинета».
  • «Сколько запросов к API осталось?»
  • «Найди ID региона Москва для таргетинга».

Как устроены объекты VK Рекламы

| Объект | Роль | |---|---| | Кампания (ad_plan) | Верхний уровень: название, бюджет, ставка и период работы. | | Группа (ad_group) | Настройки аудитории и размещения, собственные бюджет и ставка. | | Объявление (banner) | Тексты, ссылки и креатив внутри группы. | | Статистика | Отчёт по кампаниям, группам или объявлениям за период. |

У объекта есть три разных состояния. status можно менять: active, blocked или deleted. delivery и moderation_status только объясняют, почему объект показывается или нет; напрямую их изменить нельзя.

Что может изменить данные

| Действие | Что происходит | |---|---| | Списки, статистика, баланс, лимиты и регионы | Только чтение. | | Создание и обновление кампаний, групп и объявлений | Сразу создаёт или меняет объект в боевом рекламном кабинете. | | Действие со статусом | Активирует, останавливает или удаляет объект в живом кабинете. | | raw_request | GET читает данные; POST и DELETE меняют их и требуют confirmWrite=true. |

У типизированных инструментов создания, обновления и смены статуса нет внутреннего параметра confirmWrite. Как AI-приложение запрашивает подтверждение, зависит от его настроек. После сетевой ошибки или 5xx не повторяйте создание вслепую: операция могла успеть примениться, сначала проверьте список объектов.

Подключение кабинета

Скажите ассистенту:

Подключи ВК Рекламу

Он покажет, что сделать: в кабинете VK Рекламы открыть Настройки → Общие → Доступ к API, запросить доступ и прислать в чат client_id и client_secret. Секрет кабинет показывает только 10 минут после запроса и повторно не выдаёт — сохраните его сразу. Дальше сервер сам получит токен и проверит, в какой кабинет попал. Перезапускать AI-приложение и править его конфигурацию не нужно. Если секрет утерян, напишите в поддержку API VK Рекламы: [email protected].

Дальше подключение живёт само: токен VK действует около суток и продлевается автоматически по refresh_token. Проверить состояние — «покажи статус подключения», отключить — «отключи ВК Рекламу».

client_id и client_secret дают полный доступ к рекламному кабинету, включая трату бюджета. Сервер хранит их в ~/.config/mcp-vk-ads/credentials.json с правами только для владельца (0600) — client_secret нужен потому, что VK требует его при каждом продлении токена. Ни один инструмент их не возвращает.

Браузерного «войти и подтвердить» у VK Рекламы для сторонних серверов нет: сценарий authorization_code VK выдаёт только партнёрам с согласованным redirect_uri, поэтому подключение идёт через client_id и client_secret самого пользователя. Кабинеты клиентов агентства требуют гранта agency_client_credentials — для них нужен готовый токен в VK_ADS_TOKEN (см. документацию VK Ads API).

Настройка

Настраивать нечего: всё нужное сервер спрашивает в диалоге. Переменные окружения пригодятся только для CI и автоматических установок, где диалога нет. Все они необязательные — сервер работает без единой из них.

| Переменная | Назначение | |---|---| | VK_ADS_TOKEN | Готовый OAuth2 access-токен VK Ads. Имеет приоритет над входом из чата; такой токен сервер не продлевает и не удаляет. | | VK_ADS_LANG | Язык ответов API; по умолчанию ru. | | VK_ADS_TIMEOUT_MS | Таймаут одного запроса; по умолчанию 60 000 мс. | | VK_ADS_MAX_RETRIES | Число повторов при временных ошибках; по умолчанию 3. | | VK_ADS_API_BASE | Базовый адрес API; по умолчанию https://ads.vk.com/api. |

curl -X POST https://ads.vk.com/api/v2/oauth2/token.json \
  -d grant_type=client_credentials \
  -d client_id=ВАШ_CLIENT_ID \
  -d client_secret=ВАШ_CLIENT_SECRET

Из ответа возьмите access_token. Он живёт около суток и сам не продлевается: при invalid_token выпустите новый. У одного пользователя не больше 5 активных токенов на приложение; старые отзываются запросом POST /api/v2/oauth2/token/delete.json — он удаляет все токены этого пользователя для данного client_id.

Данные, лимиты и работа в фоне

  • Страницы и большие кабинеты. Одна страница списка содержит до 250 объектов. При autoPaginate сервер возвращает не более 1 000 объектов и помечает неполный результат полем _truncated.
  • Лимиты API. Инструмент get_throttling показывает текущий остаток лимитов. Проверяйте его перед массовыми операциями.
  • Повторы запросов. Таймаут одного запроса — 60 секунд. Сервер делает до трёх повторов: для любого метода при 429, а для чтения ещё при сетевой ошибке, тайм-ауте и 5xx. Задержка учитывает Retry-After и не превышает 30 секунд.
  • Нет фонового наблюдения. Сервер работает, когда его вызывает AI-приложение. Если приложение поддерживает задания по расписанию, в нём можно настроить периодический запрос статистики или статусов.
  • Анонимная телеметрия. По умолчанию сервер отправляет случайный идентификатор установки, имя события или инструмента, версии сервера, Node.js, ОС и AI-клиента. При вызове инструмента сервер также отправляет его исход, а при ошибке - фрагмент её текста: код и сообщение, в которых e-mail, адреса, токены, числа от 4 цифр и текст в кавычках заменены на «#». Если в тексте ошибки есть значение из запроса, оно тоже может попасть во фрагмент. В неё не попадают токен, данные кабинета, аргументы инструментов, ваши сообщения и значения переменных окружения. Отключить её для MCP-серверов Ask Ads: ASKADS_TELEMETRY=0.

Техническая документация

Поддержка

Нашли ошибку или не хватает сценария? Создайте issue или напишите в Telegram.