# askads/mcp-vk-ads [Health: Active]

**Category:** 🎯 Marketing  
**Repository:** https://github.com/askads/mcp-vk-ads  
**GitHub Stars:** 11  
**npm Downloads (last month):** 852  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/askads-mcp-vk-ads

## Description
VK Ads (VK Реклама) API — manage ad plans, ad groups, banners, and pull statistics. Read + write.

## Tools
Capabilities this server exposes over MCP:

- **auth_status** — Показывает, подключена ли VK Реклама: есть ли токен, откуда он взят (переменная окружения VK_ADS_TOKEN или сохранённый вход), когда истекает, какой client_id и аккаунт за ним стоят и где лежит файл с сохранёнными данными. Ничего не отправляет в сеть, не показывает ни токен, ни client_secret. Вызовите это, если инструменты VK Рекламы отвечают, что подключение не настроено.
- **start_login** — Первый шаг подключения VK Рекламы без правки конфигурации и без перезапуска клиента. Ничего не отправляет в сеть — возвращает инструкцию, которую нужно показать пользователю целиком: где в кабинете создать приложение и откуда скопировать client_id и client_secret. Полученную пару передайте в finish_login. Предупредите, что client_secret — это пароль от рекламного кабинета: он сохранится на диске только для владельца и нужен, чтобы продлевать токен.
- **finish_login** — Второй шаг подключения: обменивает client_id и client_secret из start_login на токен доступа (grant client_credentials), сохраняет всё в файл только для владельца (0600) и сразу проверяет живым запросом к VK Рекламе. После успеха остальные инструменты работают немедленно — перезапускать клиент не нужно. Токен живёт около суток и продлевается автоматически, поэтому повторно вызывать это не требуется: каждый вызов создаёт НОВЫЙ токен, а у VK не больше 5 активных токенов на пару client_id + пользователь. Ошибка invalid_client означает, что пара скопирована не полностью или относится к разным приложениям.
- **logout** — Удаляет сохранённые токен и данные приложения VK Рекламы с диска. Токен, заданный переменной окружения VK_ADS_TOKEN, не трогает — его нужно убирать из конфигурации клиента вручную. На стороне VK токен остаётся активным до истечения срока: отозвать его можно запросом POST v2/oauth2/token/delete.json, но он удаляет ВСЕ токены этого пользователя для данного client_id, поэтому здесь не вызывается.
- **get_user_info** — Возвращает информацию о текущем аккаунте VK Рекламы (user.json), включая additional_info.client_name. Позволяет убедиться, на какой аккаунт рекламодателя указывает токен.
- **get_balance** — Возвращает текущий баланс аккаунта VK Рекламы: доступные средства и валюту. Вызывает user.json с полем `account`, в котором лежит кошелёк (account.balance, account.currency). Показывает баланс того аккаунта, на который указывает токен (параметров нет). Важно: точное имя поля с балансом в v3/user.json на новой платформе ads.vk.com не подтверждено на живом кабинете (домен закрыт JS); схема следует объектной модели myTarget/VK Ads (v2/v3). Инструмент отдаёт СЫРОЙ ответ VK без изменений, поэтому вызывающая сторона может аккуратно прочитать account.balance независимо от точной формы ответа — проверить на первом живом аккаунте с доступом read_payments.
- **get_throttling** — Возвращает текущие лимиты запросов VK Рекламы и их остаток (throttling.json) — чтобы не упереться в лимит.
- **get_regions** — Возвращает гео-регионы VK Рекламы (id, name, type), при необходимости отфильтрованные по подстроке названия. Id регионов нужны для гео-таргетинга группы объявлений.
- **list_ad_plans** — Возвращает список ad_plan (верхнеуровневый объект кампании в VK Рекламе) с необязательной фильтрацией по id и статусу. Денежные поля (budget_limit, budget_limit_day, max_price) — в валюте аккаунта.
- **create_ad_plan** — Создаёт кампанию (ad_plan). Денежные поля — в валюте аккаунта. Сложные и редкие поля передаются через `extra` (подмешиваются в тело запроса как есть).
- **update_ad_plan** — Меняет у кампании название, бюджеты, предельную ставку или даты. Денежные поля — в валюте аккаунта. Для смены статуса — ad_plan_action.
- **ad_plan_action** — Меняет статус кампаний по id: activate (status=active), stop (status=blocked) или delete (status=deleted).
- **list_ad_groups** — Возвращает список групп объявлений с необязательной фильтрацией по id, родительской кампании и статусу. Денежные поля — в валюте аккаунта; в `targetings` лежит структура таргетинга по гео, демографии и интересам.
- **create_ad_group** — Создаёт группу объявлений внутри кампании. Таргетинг задаётся в `targetings` (например, {"geo":{"regions":[188]},"age":{"age_list":[25,26]}}). Денежные поля — в валюте аккаунта. Остальные поля — через `extra`.
- **update_ad_group** — Меняет у группы объявлений название, бюджеты, предельную ставку, даты или таргетинг. Денежные поля — в валюте аккаунта. Для смены статуса — ad_group_action.
- **ad_group_action** — Меняет статус групп объявлений по id: activate (status=active), stop (status=blocked) или delete (status=deleted).
- **list_banners** — Возвращает список banner (объект объявления/креатива в VK Рекламе) с необязательной фильтрацией по id, родительской группе объявлений и статусу. moderation_status (pending/allowed/banned) и delivery объясняют, почему объявление показывается или не показывается.
- **create_banner** — Создаёт объявление внутри группы объявлений. Креатив ссылается на загруженные медиа через `content`, тексты объявления — в `textblocks`, ссылки — в `urls`. Эти структуры отправляются как есть; точная форма для каждого формата объявления — в документации VK Рекламы.
- **update_banner** — Меняет у объявления название, текстовые блоки или ссылки. Для смены статуса — banner_action. Структуры отправляются как есть.
- **banner_action** — Меняет статус объявлений по id: activate (status=active), stop (status=blocked) или delete (status=deleted).
- **get_statistics** — Возвращает статистику по кампаниям (ad_plans), группам объявлений (ad_groups) или объявлениям (banners) из сервиса статистики VK Рекламы v3. По умолчанию группировка `summary` — одна сводная строка на объект за весь период; day/week/month нужны ТОЛЬКО для динамики по дням и вопросов про тренд (каждая добавляет по строке на объект за период). Ранжирование на стороне сервера — через sortBy (например, base.spent) и order; в ответе есть также `total` — сводка по ВСЕМ объектам за период (для вопросов «сколько всего» суммировать строки не нужно). Метрики лежат в `base` (shows, clicks, spent, ...); spent — в валюте аккаунта.
- **raw_request** — Универсальный запрос напрямую к любому эндпоинту API VK Рекламы (например, path "v2/ad_plans.json", method GET). Нужен для эндпоинтов, у которых нет отдельного инструмента. `query` уходит в строку запроса, `body` отправляется как JSON для POST. GET выполняется свободно; POST и DELETE — запись, для них нужен confirmWrite=true.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

**Requires environment variables:** `VK_ADS_TOKEN` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What askads/mcp-vk-ads does

askads/mcp-vk-ads exposes the VK Ads advertising hierarchy through MCP: campaigns (`ad_plan`), ad groups (`ad_group`), and banners. It can list, create, update, activate, stop, or delete these objects. Campaign and group tools handle names, budgets, bids, dates, and status actions; group operations also accept targeting data, while banner operations work with text blocks, URLs, and creative references.

Read-only tools cover the connected advertiser account, balance, API throttling limits, geographic regions, object lists, and performance reports. Statistics can be requested for campaigns, groups, or banners, with summary or time-based grouping and server-side sorting. The `raw_request` tool provides direct access to VK Ads API paths when a specialized tool is not available.

## How it works

The server runs over MCP using standard input/output and communicates with VK Ads through its API. Authentication can happen in the conversation: `start_login` explains how to create an application and obtain `client_id` and `client_secret`, while `finish_login` exchanges those values for an access token, saves the credentials with owner-only permissions, and checks the connection. Stored tokens last about a day and are renewed automatically. `auth_status`, `get_user_info`, and `logout` help inspect or remove the local connection.

VK Ads objects form a three-level structure. A campaign contains groups, and groups contain banners. Monetary values such as budgets, bids, spend, and balance use the advertising account's currency. Region IDs returned by `get_regions` can be used in group targeting, including geographic and demographic targeting structures.

## Setup and configuration

Node.js 20 or newer is required. The package can be started without a separate installation using:

```bash
npx -y mcp-vk-ads@latest
```

Add that command as an MCP server in a compatible client. The interactive login flow does not require an environment variable or a client restart. For automated or non-interactive setups, provide `VK_ADS_TOKEN`; this token is separate from the locally saved login data.

The login flow requires an application created in the VK Ads account's API access settings. The client secret is stored locally because VK Ads requires it when renewing the token. `logout` removes saved application data and tokens, but it does not remove a token supplied through `VK_ADS_TOKEN`.

## Tools and capabilities

- Inspect authentication status, advertiser identity, balance, and API request limits.
- Find VK Ads regions for campaign targeting.
- List and modify campaigns, ad groups, and banners.
- Create campaigns and groups with additional request fields through `extra`.
- Submit banner content, text blocks, and links using VK Ads structures.
- Retrieve spend, impressions, clicks, and other statistics by object level and period.
- Send direct GET, POST, or DELETE requests with `raw_request`.

## Limitations and notes

Changes apply directly to the live advertising account; VK Ads does not provide a sandbox for these operations. Status actions can activate, stop, or delete campaigns, groups, and banners. The dedicated write tools do not include an internal confirmation parameter, so confirmation behavior depends on the MCP client or calling application. For `raw_request`, GET is read-only, while POST and DELETE require `confirmWrite=true`.

After a network error or server error during creation, check the object list before retrying because the original request may have succeeded. Banner content formats follow VK Ads API requirements. The balance tool returns VK's raw response, so callers should read the account balance and currency fields from that response. Client accounts managed through an agency require a suitable pre-issued token in `VK_ADS_TOKEN`.

_Full upstream README: https://allmcps.com/mcp/askads-mcp-vk-ads/readme_