Skip to main content
Glama
Qusto

vk-ads-mcp

by Qusto
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

vk-ads-mcp

MCP-сервер для Claude Code: отдаёт статистику и структуру рекламных кампаний VK Рекламы (новый кабинет ads.vk.com, база https://ads.vk.com/api/v2).

Только чтение. Ничего не создаёт и не меняет. Рассчитан на свой кабинет.

Под капотом — тот же движок, что у myTarget. Словарь объектов: ad_plans — кампании, ad_groups — группы объявлений, banners — объявления.

Инструменты

Инструмент

Что делает

list_campaigns

список кампаний (ad_plans), фильтр по статусу, пагинация

list_ad_groups

список групп объявлений, фильтр по кампании

list_banners

список объявлений, фильтр по группе

get_statistics

статистика по ad_plans/ad_groups/banners за период (day/summary); сам режет диапазон >92 дней и список >50 id на части

get_top_objects

топ кампаний / групп / объявлений по метрике (ctr, cpc, cpa, spent и т.д.); order=asc — для метрик стоимости

describe_fields

список допустимых полей для ad_plans/ad_groups/banners — узнаёт их у API на лету

export_to_csv

выгрузка статистики в CSV-файл

get_rate_limits

остаток квоты API для диагностики

Списочные инструменты по умолчанию отдают минимальный набор полей. Чтобы получить больше данных, передайте fields (через запятую). Какие поля доступны для объекта — подскажет describe_fields.

Related MCP server: flin-meta-ads-mcp

Ресурсы и промпт

Ресурс

Что внутри

vk-ads://metrics

справочник групп метрик статистики (base, uniques, video, events, viral, carousel, tps, romi, moat, playable) с единицами измерения

vk-ads://objects

иерархия ad_plans → ad_groups → banners и ключевые поля для анализа

Промпт campaign_analysis — пошаговый сценарий разбора кампаний на русском. Принимает необязательные date_from, date_to, objective.

Анализ и рекомендации

Сервер не только отдаёт данные, но и помогает их разобрать по схеме анализ → ранжирование → рекомендации:

  1. Анализ. list_campaigns и get_statistics дают структуру и цифры за период. Ресурсы vk-ads://metrics и vk-ads://objects объясняют, что значат метрики и поля.

  2. Ранжирование. get_top_objects показывает лучшие и худшие объекты по нужной метрике: order=desc для CTR и конверсий, order=asc для cpc/cpa, где меньше — лучше.

  3. Рекомендации. Промпт campaign_analysis собирает шаги в готовый сценарий: на что смотреть, что отключить, где поднять ставку.

Доступ к API

client_id/client_secret не выдаются автоматически. В кабинете VK Рекламы: Настройки → Доступ к API → Запросить доступ к API (или письмо на ads_api@vk.team). client_secret показывают один раз. Подробнее — в исходном обзоре ../Open-Source решения для MCP Server VK Ads — полный обзор.md.

Настройка

Скопируйте .env.example в .env и задайте пару из кабинета:

VK_ADS_CLIENT_ID=...
VK_ADS_CLIENT_SECRET=...

Сервер сам получит и обновит токен через grant_type=client_credentials (и перезапросит при 401). Если когда-нибудь окажется готовый Bearer-токен — можно вместо пары задать VK_ADS_TOKEN, тогда OAuth не используется.

.env в git не попадает. .mcp.json хранит только плейсхолдеры ${VK_ADS_CLIENT_ID} / ${VK_ADS_CLIENT_SECRET}.

VK ограничивает кабинет 5 живыми токенами на client_id, а Claude Code часто перезапускает сервер. Поэтому токен кешируется на диск (~/.cache/vk-ads-mcp/token.json, права 0600) и переиспользуется между перезапусками — новый токен не выпускается, пока старый не истёк. Путь меняется через VK_ADS_TOKEN_CACHE.

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

claude mcp add vk-ads --scope project \
  --env VK_ADS_CLIENT_ID=$VK_ADS_CLIENT_ID \
  --env VK_ADS_CLIENT_SECRET=$VK_ADS_CLIENT_SECRET \
  -- uv run --with fastmcp fastmcp run src/vk_ads_mcp/server.py

Команда дописывает .mcp.json в корень проекта (он уже здесь). Реальный токен берётся из окружения при запуске, в репозиторий не коммитится.

Разработка

uv sync --all-extras --dev
uv run pytest -q          # тесты, сеть не нужна (httpx замокан через respx)
uv run ruff check .       # линт
uv run ruff format .      # форматирование

Отладка вручную

uv run fastmcp dev src/vk_ads_mcp/server.py

Поднимает MCP Inspector — можно дёргать инструменты руками и смотреть ответы.

Структура

src/vk_ads_mcp/
  app.py          общий FastMCP-инстанс + ленивый клиент
  config.py       чтение env
  auth.py         OAuth2 client_credentials + refresh / Bearer-override
  client.py       весь HTTP: пагинация, чанкинг 92 дней / 50 id, бэкофф на 429
  models.py       pydantic-модели ответов
  tools/          по файлу на инструмент
  resources.py    ресурсы vk-ads://metrics и vk-ads://objects
  prompts.py      промпт campaign_analysis
  server.py       точка входа (регистрирует инструменты, ресурсы, промпт, запускает stdio)
tests/            pytest + respx

Available Tools

8 tools
describe_fieldsA
Read-onlyIdempotent

Discover which fields a VK Ads resource accepts. Call this FIRST.

Call this before the list tools to learn which fields you can request, then pass the ones you need as the fields argument of list_campaigns, list_ad_groups or list_banners. The valid set is discovered live against the cabinet, so it always reflects the real API.

How it works: the tool sends a request carrying one deliberately-invalid field. The API rejects it with HTTP 400 and a body listing every allowed field, which this tool parses and returns.

ParametersJSON Schema
NameRequiredDescriptionDefault
resourceYesOne of ``"ad_plans"`` (campaigns), ``"ad_groups"`` or ``"banners"``.

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint. Description adds specific mechanism: sends invalid field to trigger HTTP 400 and parses allowed fields. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three well-structured sentences: purpose, usage instructions, and how-it-works. No fluff, each sentence serves a distinct purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists (not shown but stated true). Description covers live behavior and prerequisites. Complete for a simple parameter tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage 100% with clear parameter description. Description adds value by mapping resource values to sibling tool names (e.g., 'ad_plans' for campaigns).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb+resource: 'Discover which fields a VK Ads resource accepts. Call this FIRST.' Distinct from sibling list tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to call before list tools and names them (list_campaigns, list_ad_groups, list_banners). Provides when-not-to-use context by stating it's a prerequisite.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

export_to_csvA
Idempotent

Export VK Ads statistics to a CSV file on disk.

Fetches statistics for the given object type and date range via the shared client (which transparently splits ranges longer than 92 days and id lists longer than 50 into multiple requests), flattens each returned item into a CSV row using the stdlib :mod:csv module, and writes the result to output_path. Read-only: it never mutates any ad object.

The CSV header is the union of every key seen across all items, in first-seen order. Missing values for a given row are written as empty cells. All values are stringified.

ParametersJSON Schema
NameRequiredDescriptionDefault
object_typeYesOne of ``ad_plans`` (campaigns), ``ad_groups``, or ``banners``. An invalid value raises an error.
date_fromYesInclusive start date in ``YYYY-MM-DD`` format.
date_toYesInclusive end date in ``YYYY-MM-DD`` format.
output_pathYesFilesystem path where the CSV file is written. An existing file at this path is overwritten.
periodNo``day`` for a per-day breakdown or ``summary`` for a single aggregated row per object. Defaults to ``day``.day
metricsNoMetrics group to request, e.g. ``base``, ``all``, ``uniques``, or ``video``. Defaults to ``base``.base

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description provides significant behavioral detail beyond annotations: it explains that the client splits long ranges (>92 days) and id lists (>50), flattens items into CSV rows using stdlib, writes to a file, and specifies header behavior and missing value handling. It also clarifies it never mutates ad objects, adding context to the annotation readOnlyHint=false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured, starting with a clear purpose sentence, followed by detailed behavior, and then CSV specifics. It is concise yet comprehensive, with no unnecessary words. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool complexity (6 parameters, output schema exists), the description covers all necessary aspects: splitting behavior, CSV format, header union, missing values, and side effects (file overwrite). It aligns with annotations and schema, providing a complete understanding without requiring the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, providing baseline score of 3. The description adds extra meaning by explaining how the client transparently splits date ranges and id lists, and implies that invalid object_type raises an error. This adds value beyond the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with 'Export VK Ads statistics to a CSV file on disk', clearly stating the verb (export) and resource (VK Ads statistics). It further specifies the object type and date range, distinguishing it from sibling tools like get_statistics which return JSON, and it mentions read-only behavior, setting it apart from mutation tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use this tool (to export statistics to CSV) and transparently handles range splitting and id list splitting. However, it does not explicitly state when not to use it or directly compare to sibling alternatives like get_statistics or get_top_objects, leaving the agent to infer the best use case.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_rate_limitsA
Read-onlyIdempotent

Report remaining VK Ads API quota for diagnostics.

Combines two sources of throttling information:

  • A live GET /throttling.json call returning the API's current view of remaining requests per second, per hour, and per day (throttling).

  • The last X-RateLimit-* header values observed on any prior request, cached on the shared client (last_seen).

Use this to check how much API budget is left before issuing further listing or statistics requests, or to debug HTTP 429 rate-limit errors.

Returns: A dict with two keys:

* ``throttling``: the decoded ``/throttling.json`` body (remaining and
  limit values for rps/hourly/daily quotas, as returned by the API).
* ``last_seen``: the most recent rate-limit header values observed by
  the client (``rps_remaining``, ``hourly_remaining``,
  ``daily_remaining``); values are ``None`` until a request has run.
ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint true. The description adds context about combining two sources (live call and cached headers) and confirms it's a safe diagnostic operation, adding value beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured: a concise summary, bullet points explaining two sources, and a usage recommendation. No unnecessary words; every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter diagnostic tool, the description fully explains what it does, the data sources, the return format, and when to use it. No gaps given the simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has no parameters (0 params, 100% coverage), so baseline is 4. The description does not need to add parameter info as there are none.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it reports remaining VK Ads API quota for diagnostics, naming specific data sources (live throttling call and cached headers). It distinguishes itself from siblings by focusing on quota diagnostics rather than data retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Use this to check how much API budget is left before issuing further listing or statistics requests, or to debug HTTP 429 rate-limit errors.' It provides clear context but does not explicitly exclude other uses or mention alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_statisticsA
Read-onlyIdempotent

Fetch performance statistics for VK Ads objects.

Retrieves statistics from GET /statistics/{object_type}/{period}.json and returns a merged {"items": [...]} payload. The underlying client transparently handles the API's hard limits: date ranges longer than 92 days are split into multiple inclusive windows, and id lists longer than 50 are chunked, with all responses merged into a single result. The caller never has to worry about those limits.

ParametersJSON Schema
NameRequiredDescriptionDefault
object_typeYesThe object level to report on. One of: * ``"ad_plans"`` — campaign-level statistics. * ``"ad_groups"`` — ad-group-level statistics. * ``"banners"`` — banner (creative) level statistics.
date_fromNoInclusive start date in ``YYYY-MM-DD`` format (e.g. ``"2025-01-01"``). When omitted the API applies its own default window. Mostly relevant for ``period="day"``.
date_toNoInclusive end date in ``YYYY-MM-DD`` format (e.g. ``"2025-01-31"``). Must not precede ``date_from``. When omitted the API applies its own default window.
periodNoThe aggregation period. One of: * ``"day"`` (default) — one row per day in the date range; use this for time-series breakdowns. * ``"summary"`` — a single aggregated total over the whole range.day
idsNoOptional list of object ids to restrict the report to (campaign, ad-group or banner ids matching ``object_type``). When omitted, statistics are returned for all objects of that type.
metricsNoThe metrics group to include. One of: * ``"base"`` (default) — core delivery metrics (shows, clicks, spent, CTR, CPC, CPM, etc.). * ``"all"`` — every available metric group. * ``"uniques"`` — reach / unique-users metrics. * ``"video"`` — video-specific metrics (views, view depth, etc.).base

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds significant value beyond annotations by revealing that the client transparently splits date ranges over 92 days and chunks id lists over 50, merging results. This discloses behavior not evident from readOnlyHint and idempotentHint alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise at 5 sentences, front-loaded with a clear purpose, and uses efficient language. Every sentence adds value without repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool complexity (6 parameters, 1 required) and presence of an output schema, the description fully covers purpose, behavior, and parameter-related constraints. No gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds context about how parameters relate to API limits (e.g., date_from/date_to splitting, ids chunking), providing meaning beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Fetch performance statistics for VK Ads objects' and explains the API endpoint. It distinguishes this tool from siblings like 'get_top_objects' or 'list_campaigns' by focusing on statistics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool (retrieving statistics) and explains that the client handles API limits automatically. However, it does not explicitly compare to alternatives or state when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_top_objectsA
Read-onlyIdempotent

Rank VK Ads objects by a performance metric and return the top N.

Fetches statistics via the shared client, reads the chosen metric from each object's total.base aggregate, sorts the objects, and returns the best (or worst) limit of them. Use this to pick the best-performing (or worst-performing) campaigns, ad groups or banners.

ParametersJSON Schema
NameRequiredDescriptionDefault
object_typeYesOne of ``"ad_plans"`` (campaigns), ``"ad_groups"`` or ``"banners"``.
metricYesThe metric to rank by, taken from ``total.base``, e.g. ``"ctr"``, ``"cpc"``, ``"cpa"``, ``"spent"``, ``"clicks"``, ``"shows"``, ``"cpm"``, ``"cr"``, ``"goals"``.
date_fromNoInclusive start date ``YYYY-MM-DD``. Pair with ``date_to``.
date_toNoInclusive end date ``YYYY-MM-DD``. Pair with ``date_from``.
limitNoHow many top objects to return (default 10). Clamped to >= 1.
orderNo``"desc"`` (default, best/highest first) or ``"asc"`` (lowest first — handy for cost metrics like ``cpc``/``cpa``).desc
periodNo``"summary"`` (default, one aggregate per object) or ``"day"``. Ranking always uses the per-object ``total.base`` aggregate.summary
metricsNoMetrics group to request (default ``"base"``).base

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations (readOnlyHint, idempotentHint), the description adds details: fetches via shared client, reads metric from total.base aggregate, sorts, and returns top/bottom limit. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences plus a usage directive; all content is relevant and front-loaded. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and 100% parameter coverage, the description fills the remaining gaps by explaining the ranking logic, metric source, and usage intent. It is complete for a tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds context like 'from each object's total.base aggregate' but does not significantly enhance parameter meaning beyond the schema's own descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb (rank) and the resource (VK Ads objects by a performance metric, returning top N). It distinguishes from sibling tools like list_ad_groups by focusing on ranking and selection of best/worst performers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Use this to pick the best-performing (or worst-performing) campaigns, ad groups or banners.' However, it does not contrast with sibling tools like get_statistics for raw data or list_* for unfiltered listings, but the usage context is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_ad_groupsA
Read-onlyIdempotent

List ad groups (VK Ads ad_group objects) in the connected cabinet.

Ad groups live inside campaigns (ad_plan objects) and contain the individual banners (creatives). This read-only tool drains every page of the /ad_groups.json listing endpoint and returns the RAW item dicts so every requested field reaches you for analysis.

By default the API returns a MINIMAL field set. Pass fields to get rich data, e.g. "id,name,status,targetings,utm,banners,package_id". The targetings field exposes age/gender/geo/interests. Call the describe_fields tool with resource="ad_groups" first to learn the full set of valid field names.

ParametersJSON Schema
NameRequiredDescriptionDefault
ad_plan_idNoRestrict results to ad groups belonging to this campaign (``ad_plan``) id. Sent to the API as the ``_ad_plan_id__in`` filter. When omitted, ad groups from every campaign are returned.
fieldsNoOptional comma-separated list of object fields to request from the API. Forwarded verbatim as the ``fields`` query parameter. Rich fields include ``targetings``, ``utm``, ``banners``, ``package_id`` — see ``describe_fields``.
statusNoRestrict results to ad groups with this status (e.g. ``"active"`` or ``"blocked"``). Sent to the API as the ``_status__in`` filter.
sortingNoOptional sort spec, e.g. ``"-id"`` or ``"id"``. Forwarded verbatim as the ``sorting`` query parameter.
limitNoPage size for pagination (1-50). The API caps page size at 50; larger values are clamped. This affects request batching only — all matching ad groups are returned regardless.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes beyond the annotations (readOnlyHint, idempotentHint) by explaining pagination behavior ('drains every page'), return format ('RAW item dicts'), and default field set. This adds substantial context that structured fields alone do not provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (5 sentences), well-structured, and front-loaded with the core purpose. Each sentence adds value without redundancy, and it follows a logical flow from what the tool does to how to use it effectively.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool complexity (5 optional parameters, pagination, field selection), the description is remarkably complete. It explains the tool's role in the API hierarchy, provides usage examples, references a sibling tool for field discovery, and clarifies pagination behavior. With annotations and output schema present, no critical information is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100% and the schema descriptions are detailed, the description adds extra context for the 'fields' parameter with examples and reference to 'describe_fields', and clarifies that 'limit' affects batching but not result completeness. This enriches parameter understanding beyond schema basics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists ad groups, explains the hierarchy with campaigns and banners, and distinguishes itself from sibling tools by focusing on ad group objects. It uses specific verbs and resource types, making the purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides usage guidance by mentioning the optional 'fields' parameter and recommending calling 'describe_fields' first to learn valid field names. It implies read-only usage, but does not explicitly compare to alternatives like 'list_banners' or 'get_statistics'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_bannersA
Read-onlyIdempotent

List banners (creatives) in the own VK Ads cabinet.

Fetches every banner from GET /banners.json, transparently paginating over all result pages, and returns the RAW item dicts so every requested field reaches you for analysis. Read-only.

By default the API returns a MINIMAL field set. Pass fields to get rich creative data, e.g. "id,status,content,textblocks,urls,moderation_status". The content field carries the creative variants/urls. Call the describe_fields tool with resource="banners" first to learn the full set of valid field names.

ParametersJSON Schema
NameRequiredDescriptionDefault
ad_group_idNoRestrict results to banners belonging to this ad group. Mapped to the API filter ``_ad_group_id__in``.
fieldsNoOptional comma-separated list of fields to request from the API. Forwarded verbatim as the ``fields`` param. Rich fields include ``content``, ``textblocks``, ``urls``, ``moderation_status`` — see ``describe_fields``.
statusNoRestrict results to banners with this status (e.g. ``active``, ``blocked``). Mapped to the API filter ``_status__in``.
sortingNoOptional sort spec, e.g. ``"-id"`` or ``"id"``. Forwarded verbatim as the ``sorting`` query parameter.
limitNoPage size for pagination (1-50). The API caps page size at 50; larger values are clamped. This affects request batching only — all matching banners are returned regardless.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (readOnlyHint, idempotentHint), the description adds valuable behavioral details: transparent pagination, returning raw item dicts, default minimal field set, and the effect of the 'fields' parameter. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is four sentences, front-loaded with purpose, and every sentence adds value—pagination, read-only, field selection, and a pointer to describe_fields. No redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the existence of an output schema and annotations, the description covers all needed context: what the tool does, pagination behavior, read-only nature, parameter usage tips, and how to explore fields. It is self-contained and sufficient for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, providing baseline 3. The description adds meaning beyond schema with examples (e.g., 'content' field carries variants/urls) and behavioral notes (limit clamping, all banners returned). This incremental value justifies a score of 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List banners (creatives) in the own VK Ads cabinet.' with a specific verb and resource. Although it does not explicitly contrast with sibling tools, the resource 'banners' is distinct from 'ad_groups' or 'campaigns' in sibling names, making it unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on how to use the tool, including parameter guidance (e.g., pass 'fields' for rich data) and a recommendation to call 'describe_fields' first. It lacks explicit when-not-to-use or alternatives, but the context is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_campaignsA
Read-onlyIdempotent

List ad campaigns (VK Ads ad_plans) for the authenticated cabinet.

Fetches every campaign from GET /ad_plans.json, transparently walking the offset-based pagination, and returns the RAW item dicts so every field you request reaches you for analysis.

By default the API returns a MINIMAL field set. To get rich data pass fields with the columns you need, e.g. "id,name,status,objective,budget_limit,budget_limit_day,autobidding_mode," "max_price,priced_goal,delivery,efficiency_status,date_start,date_end". Call the describe_fields tool with resource="ad_plans" first to learn the full set of valid field names for this resource.

ParametersJSON Schema
NameRequiredDescriptionDefault
fieldsNoOptional comma-separated list of object fields to request from the API. Forwarded verbatim as the ``fields`` query parameter. When ``None`` the API default (minimal) field set is returned. Rich fields include ``objective``, ``budget_limit_day``, ``autobidding_mode``, ``priced_goal``, ``delivery``, ``efficiency_status`` — see ``describe_fields``.
statusNoOptional campaign status to filter by (sent as the ``_status__in`` filter), e.g. ``"active"``, ``"blocked"``, ``"deleted"``. When ``None`` no status filter is applied.
sortingNoOptional sort spec, e.g. ``"-id"`` (newest first) or ``"id"``. Forwarded verbatim as the ``sorting`` query parameter.
limitNoPage size for pagination (1-50). The API caps page size at 50; larger values are clamped. This affects request batching only — all matching campaigns are returned regardless.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses pagination walking, raw dict return, and default field behavior, adding value beyond the `readOnlyHint` and `idempotentHint` annotations. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise and front-loaded: 5 sentences cover purpose, pagination, field selection, and reference to another tool. No superfluous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers main aspects: what it does, pagination, field selection, and integration with `describe_fields`. With output schema present, return values are documented elsewhere. Minor omission of error handling but not critical.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds meaning: provides example for fields parameter, explains status filter, sorting, and limit with clamping. This goes beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists ad campaigns (VK Ads `ad_plans`) for the authenticated cabinet, with a specific verb and resource. It distinguishes from siblings like `list_ad_groups` and `list_banners` by naming the resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context: mentions default minimal field set, suggests using `describe_fields` first to learn valid fields, and explains how to get rich data. While it doesn't explicitly say when not to use, the guidance is sufficient for an AI agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 8 tool updatesv0.1.0
    • First observeddescribe_fields
    • First observedexport_to_csv
    • First observedget_rate_limits
    • First observedget_statistics
    • First observedget_top_objects
    • First observedlist_ad_groups
    • First observedlist_banners
    • First observedlist_campaigns
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.5/5.0

Scored across 8 tools

Disambiguation5/5

Every tool targets a distinct resource or operation (field discovery, listing campaigns/ad groups/banners, statistics, export, rate limits). No two tools overlap in functionality, so an agent can easily distinguish them.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern in snake_case (e.g., describe_fields, get_statistics, list_campaigns). The naming is predictable and clear.

Tool Count4/5

With 8 tools, the set is well-scoped for a read-only analytics-oriented VK Ads server. It covers listing, statistics, export, and diagnostics without being too sparse or overly bloated.

Completeness3/5

The tools cover listing, statistics, and export well, but lack any write operations (create, update, delete) for campaigns, ad groups, or banners. For a full ad management server, this is a notable gap, though the set is coherent for read-only analytics.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • vk-ads-mcp

    theYahia
    A
    license
    B
    quality
    A
    maintenance
    MCP server for VK Ads API enabling management of campaigns, ads, statistics, targeting, and budgets through natural language.
    8
    19
    4
    MIT

  • flin-meta-ads-mcp

    flin-agency
    A
    license
    B
    quality
    B
    maintenance
    Read-only MCP server for Meta Ads that lists and reads ad accounts, campaigns, ad sets, ads, ad images, creatives, and fetches insights at various levels.
    14
    MIT

  • VK Ads MCP

    askads
    A
    license
    A
    quality
    A
    maintenance
    MCP server for VK Ads API: manage ad plans, ad groups, banners, and statistics.
    18
    43
    7
    MIT

  • VK Ads MCP All in One

    sergeylopukhov
    A
    license
    Not graded
    quality
    A
    maintenance
    Local MCP server that integrates with VK Ads API and Core VK API, providing 128 tools for managing ad campaigns, audiences, creatives, statistics, and analyzing VK communities.
    0
    MIT