ad_group_action
Changes the lifecycle status of ad groups by id: activate (status=active), stop (status=blocked) or delete (status=deleted).
LABSCO SUMMARY
The whole VK Ads object hierarchy, with money already in account currency.
Bids, budgets and spend come back in the account's currency rather than raw micro-units, which is what makes an assistant's arithmetic on them trustworthy. Reads are the safe half; creates and status actions apply immediately, because VK Ads offers no sandbox to rehearse in.
What it is
An MCP server for the VK Ads API. It maps the account hierarchy — ad plan, ad group, banner — onto tools, so an assistant can compare spend across groups, change a bid, or build a new campaign in one conversation instead of walking the dashboard.
What you get
- get_user_info, get_balance and get_throttling — confirm which advertiser account the token points at, read available funds and currency, and check remaining request budget
- list_ad_plans, create_ad_plan, update_ad_plan and ad_plan_action — campaigns with their budgets, bid caps and dates; the action tool activates, stops or deletes them
- list_ad_groups, create_ad_group, update_ad_group and ad_group_action — the same lifecycle for ad groups, with geo, demographic and interest targeting passed in targetings
- list_banners, create_banner, update_banner and banner_action — creatives with their text blocks and links; moderation_status and delivery show why an ad is not running
- get_statistics — performance from the VK Ads v3 statistics service for plans, groups or banners, aggregated per object by default
- get_regions — geo region ids needed for ad group targeting
- raw_request — call any VK Ads endpoint that has no dedicated tool
Requirements
A VK Ads OAuth2 access token in VK_ADS_TOKEN, which carries full account access. Clients run it with npx mcp-vk-ads over stdio and need Node.js 20 or newer. VK_ADS_LANG sets the response language (default ru); VK_ADS_API_BASE, VK_ADS_TIMEOUT_MS and VK_ADS_MAX_RETRIES override the endpoint, per-request timeout and retry count. VK Ads has no sandbox, so creates, updates and status changes land in the live account.
Setup effort
One command plus a key — npx -y mcp-vk-ads@latest, then supply credentials
USE CASES
01
Finding campaigns burning budget with nothing to show
Pull last week's statistics per ad group, then read the plan budgets and account balance alongside them.
02
Working out why an ad stopped delivering
List the banners under a group and read their moderation status and delivery state.
03
Launching a new campaign
Look up the region ids you need, create the plan and group with targeting, then attach a creative.
04
Pausing spend in a hurry
Stop the plans or groups by id without opening the dashboard.
18 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
ad_plan_action
Changes the lifecycle status of ad plans by id: activate (status=active), stop (status=blocked) or delete (status=deleted).
banner_action
Changes the lifecycle status of banners by id: activate (status=active), stop (status=blocked) or delete (status=deleted).
create_ad_group
Creates an ad group inside an ad plan. Targeting goes in targetings (e.g. {"geo":{"regions":[188]},"age":{"age_list":[25,26]}}). Money fields are in account currency. Use extra for any other field.
create_ad_plan
Creates an ad plan (campaign). Money fields are in account currency. Pass complex or less common fields via extra (merged into the request body verbatim).
create_banner
Creates a banner inside an ad group. Creative content references uploaded media via content, ad copy goes in textblocks and links in urls. These structures are sent verbatim; consult the VK Ads docs for the exact shape per ad format.
get_balance
Returns the current VK Ads account balance: available funds and currency. Calls user.json with the account field, which carries the wallet (account.balance, account.currency). Reports the balance of the account the token points at (no parameters). Note: the exact balance field name in v3/user.json on the new ads.vk.com platform is not confirmed against a live cabinet (the domain is JS-gated); the schema follows the myTarget/VK Ads object model (v2/v3). This tool returns the RAW VK response unchanged, so a caller can read account.balance defensively regardless of the exact shape — verify on the first live account with read_payments.
get_regions
Lists VK Ads geo regions (id, name, type), optionally filtered by a name substring. Region ids are needed for ad group geo targeting.
get_statistics
Fetches performance statistics from the VK Ads v3 statistics service for ad plans, ad groups or banners. By default the grouping is summary — one aggregated row per object over the whole period; use day/week/month ONLY for daily dynamics or trend questions (each adds a row per object per period). Rank objects server-side with sortBy (e.g. base.spent) + order; the response also carries total — the summary across ALL objects for the period (use it for «сколько всего», no need to sum rows). Metrics live under base (shows, clicks, spent, ...); spent is in account currency.
get_throttling
Returns the current VK Ads request limits and remaining budget (throttling.json), so you can avoid hitting the rate limit.
get_user_info
Returns information about the current VK Ads account (user.json), including additional_info.client_name. Use it to confirm which advertiser account the token points at.
list_ad_groups
Lists ad groups with optional filtering by id, parent ad plan and status. Money fields are in the account currency; targetings holds the geo/demographic/interest targeting structure.
list_ad_plans
Lists ad plans (the top-level VK Ads campaign object) with optional filtering by id and status. Money fields (budget_limit, budget_limit_day, max_price) are in the account currency.
list_banners
Lists banners (the VK Ads creative/ad object) with optional filtering by id, parent ad group and status. moderation_status (pending/allowed/banned) and delivery show why an ad is or isn't showing.
raw_request
Escape hatch to call any VK Ads API endpoint directly (e.g. path "v2/ad_plans.json", method GET). Use this for endpoints that have no dedicated tool. query becomes the query string; body is sent as JSON for POST. GET runs freely; POST and DELETE are writes and require confirmWrite=true.
update_ad_group
Updates an ad group's name, budgets, bid cap, dates or targeting. Money fields are in account currency. Use ad_group_action to change status.
update_ad_plan
Updates an ad plan's name, budgets, bid cap or dates. Money fields are in account currency. Use ad_plan_action to change status.
update_banner
Updates a banner's name, text blocks or links. Use banner_action to change status. Structures are sent verbatim.
BEFORE YOU INSTALL
What to know first
Tools you get
18 tools when we connected. raw_request calls any VK Ads endpoint by path and method, so the whole API is reachable. moderation_status is a read-only banner field, not a tool.
Requires
- npx on PATH
- VK_ADS_TOKEN in your environment
CONTEXT COST
Moderate Standing cost
Rated by the size of the 18 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
npx -y mcp-vk-ads@latestMCP Clients
Codex
CODEX · TERMINAL
codex mcp add vk-ads \
--env VK_ADS_TOKEN=<YOUR_VK_ADS_TOKEN> \
-- npx -y mcp-vk-ads@latestClaude Code
CLAUDE CODE · TERMINAL
claude mcp add \
--env VK_ADS_TOKEN=<YOUR_VK_ADS_TOKEN> \
--transport stdio \
--scope user \
vk-ads \
-- npx -y mcp-vk-ads@latestClaude Desktop, Cursor
JSON
{
"mcpServers": {
"vk-ads": {
"command": "npx",
"args": [
"-y",
"mcp-vk-ads@latest"
],
"env": {
"VK_ADS_TOKEN": "<YOUR_VK_ADS_TOKEN>"
}
}
}
}VS Code
VS CODE · JSON
{
"servers": {
"vk-ads": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mcp-vk-ads@latest"
],
"env": {
"VK_ADS_TOKEN": "${input:vk_ads_token}"
}
}
},
"inputs": [
{
"type": "promptString",
"id": "vk_ads_token",
"description": "VK Ads access token",
"password": true
}
]
}
