MCP Vk Ads logo

MCP Vk Ads

by askads

Manage VK Ads campaigns, targeting, creatives, budgets, authentication, and performance reports through MCP.

Install MCP Vk Ads

Run the project’s own setup commands, in order.

Setup steps from the project

askads/mcp-vk-ads installs with its own commands rather than a config we can generate, so these are copied as-is. Run them in order in a terminal. Source: github.com

  1. 1. Start the server
    npx -y mcp-vk-ads@latest
    
  2. 2. Add to Codex
    codex mcp add vk-ads -- npx -y mcp-vk-ads@latest
    
  3. 3. Add to Claude Code
    claude mcp add \
      --transport stdio \
      --scope user \
      vk-ads \
      -- npx -y mcp-vk-ads@latest
    

Overview

askads/mcp-vk-ads connects MCP-compatible AI clients to the VK Ads API for reading and changing campaigns, ad groups, banners, account data, and statistics. It models the VK Ads hierarchy from campaigns (`ad_plan`) to groups (`ad_group`) and creatives (`banner`), with tools for budgets, targeting, statuses, regions, balance, and throttling. Authentication can be completed in the conversation with a VK `client_id` and `client_secret`, while tokens are stored locally and refreshed automatically. Reach for it when an agent needs to inspect VK advertising performance or apply controlled changes directly to a live advertising account.

Use cases

  • Compare campaign, group, and banner spend over a selected period
  • Create or update VK Ads campaigns, budgets, targeting, and creatives
  • Check account balance, currency, token status, and API limits
  • Find regions and IDs for geographic ad targeting
  • Inspect moderation and delivery reasons for banners

Key features

  • VK Ads campaign, ad group, and banner management
  • Performance statistics with time grouping and server-side sorting
  • Interactive client-credentials authentication with automatic token renewal
  • Balance, advertiser identity, API throttling, and region lookup
  • Live status actions for activation, stopping, and deletion
  • Generic VK Ads API requests through raw_request

Tools22

What MCP Vk Ads lets your agent do. Expand a tool for its parameters.

Verified live~4.8k tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked Today

Recent health check succeeded.

22/22 checks healthy over the last 92d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 22d ago via OSV.dev

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars12Stargazers on the source repository.
Last commit9d agoMost recent push to the default branch.
Tools exposed22Callable tools this server registers over MCP.
Directory activity4 viewsConfig copies, upvotes, and views on AllMCPs.

How MCP Vk Ads works

What askads/mcp-vk-ads does

askads/mcp-vk-ads exposes the VK Ads API as MCP tools for account inspection, campaign management, and reporting. It follows VK Ads’ three-level structure: an ad_plan is the campaign, an ad_group contains audience and placement settings, and a banner contains the ad text, links, and creative references.

Read operations cover the current advertiser account, balance and currency, API request limits, geographic regions, campaign and group listings, banner moderation and delivery information, and performance data. The statistics tool can report on campaigns, groups, or banners for a selected period. Results can be grouped as a summary or by day, week, or month, and can be sorted by metrics such as spend.

Write operations create and update campaigns, groups, and banners. Separate action tools activate, stop, or delete those objects. Monetary values use the account’s currency. The extra, targetings, content, textblocks, and urls fields allow VK-specific request structures to be passed through where the typed parameters do not cover every format.

How it works

The server uses the VK Ads API over MCP. Authentication can begin with start_login, which explains how to create an application and find its credentials. finish_login exchanges the supplied client credentials for an access token, stores the authentication data for the local owner, and validates the connection with a live VK request. Tokens last about a day and are renewed automatically. auth_status, get_user_info, and logout help inspect or remove the local connection.

For endpoints without a dedicated tool, raw_request sends a request to a specified VK Ads API path. Query parameters are placed in the URL, while POST bodies are sent as JSON. GET requests are read operations; POST and DELETE require confirmWrite=true.

Setup and configuration

Node.js 20 or newer is required. The package can run directly through npx, so a separate installation is not necessary:

Terminal
npx -y mcp-vk-ads@latest

Add that command as a stdio MCP server in the client of choice. Documented configurations are available for Codex, Claude Code, Claude Desktop, Cursor, and VS Code. The server can be connected without environment variables, then authorized through the conversation. For a non-interactive setup, VK_ADS_TOKEN can provide an existing token.

Interactive login stores credentials in ~/.config/mcp-vk-ads/credentials.json with owner-only permissions (0600). The stored client secret is used when renewing the token and is not returned by the tools. Agency client accounts that require the agency_client_credentials grant use a pre-existing token through VK_ADS_TOKEN.

Tools and capabilities

  • Inspect authentication state, advertiser identity, balance, and API throttling.
  • Search VK Ads regions for IDs used in geographic targeting.
  • List, create, and update campaigns and ad groups.
  • Set campaign, group, and banner statuses to active, blocked, or deleted.
  • List, create, and update banners, including text, URLs, and creative references.
  • Retrieve statistics with date ranges, grouping, sorting, and totals.
  • Send supported direct API requests through raw_request.

Limitations and notes

Changes apply to the live VK Ads account; there is no sandbox. Campaign, group, and banner creation, updates, and status actions can affect delivery or spend immediately. The client should verify object IDs, budgets, and amounts before writing. After a network error or server error during creation, check the object list before retrying because the change may already have been applied.

The delivery and moderation_status values explain why an ad is or is not being shown, but they are not directly editable. Banner payload structures depend on the VK Ads format and must follow VK’s API expectations. Balance data is returned as VK’s raw response, allowing the caller to inspect the account balance and currency fields.

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about MCP Vk Ads

askads/mcp-vk-ads is an MCP server that connects AI clients to the VK Ads API. Its main tools authenticate accounts, inspect balances and limits, list or modify campaigns, ad groups, and banners, retrieve statistics, find targeting regions, and send supported raw API requests.

Run it with Node.js 20 or newer using `npx -y mcp-vk-ads@latest`. Add that command as a stdio MCP server in your client configuration; the documented setup covers Codex, Claude Code, Claude Desktop, Cursor, and VS Code.

Start the login flow through the MCP client, then provide the `client_id` and `client_secret` from a VK Ads application. The server exchanges them for a token, validates the account, stores credentials with owner-only permissions, and renews the token automatically.

Yes, askads/mcp-vk-ads works with Cursor through a stdio entry in `.cursor/mcp.json` or the user-level `~/.cursor/mcp.json`. The command uses `npx -y mcp-vk-ads@latest`, and no environment variables are needed for interactive login.

Related MCP servers

Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewMCP Vk Ads AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/askads-mcp-vk-ads?style=directory)](https://allmcps.com/mcp/askads-mcp-vk-ads)
HTML Embed
<a href="https://allmcps.com/mcp/askads-mcp-vk-ads"><img src="https://allmcps.com/api/badge/askads-mcp-vk-ads?style=directory" alt="MCP Vk Ads on AllMCPs" /></a>