VK Реклама MCP

VK Реклама MCP connects an AI app to the VK Ads advertising account. You can ask which campaigns spend budget without results, compare ad groups and ads, prepare a new campaign, or change a bid. Unlike manually navigating the account sections, the assistant matches campaigns, statistics, balance, and statuses in one dialogue.

• 18 tools. Campaigns, ad groups, ads, statistics, balance, API limits, regions, and a universal API request.

• Live advertising. Bids, budgets, and spend are shown in the advertising account's currency — no micro-unit conversion.

• Full hierarchy. Campaign (ad_plan) → ad group (ad_group) → ad (banner).

• Analysis first. Lists, reports, balance, and statuses are read-only.

• Changes go to the live account. Creating, updating, and status actions apply immediately; VK Ads has no sandbox.

Start with a safe request:

Show the campaigns of my VK Рекламы account and spend for the past week by ad groups.

Connect server · View scenarios · Open technical documentation

See it work in a minute

Related MCP server: vk-ads-mcp

Contents

• Quick start

• What you can delegate

• How VK Рекламы objects work

• What can change data

• How to get a token

• Configuration

• Data, limits, and background operation

• Technical documentation

• Support

Quick start

You need Node.js 20 or newer and a VK Ads access token. The server runs via npx, so you don't need to install the package separately.

1. Get a token and add the server to your AI app — instructions for five apps below.

2. Ask: "Show the campaigns of my VK Рекламы account and spend for the past week by ad groups."

Via the app interface:

1. Open Settings → Plugins → MCP servers.

2. Click Add server.

3. Add the launch command npx -y mcp-vk-ads@latest and the environment variable VK_ADS_TOKEN with your token.

Via the command line:

codex mcp add vk-ads \
  --env VK_ADS_TOKEN=ваш_токен \
  -- npx -y mcp-vk-ads@latest

Check the connection:

codex mcp list

Official Codex guide

claude mcp add \
  --env VK_ADS_TOKEN=ваш_токен \
  --transport stdio \
  --scope user \
  vk-ads \
  -- npx -y mcp-vk-ads@latest

Check the server:

claude mcp list

Claude Code documentation

Open Settings → Developer → Edit Config and add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "vk-ads": {
      "command": "npx",
      "args": ["-y", "mcp-vk-ads@latest"],
      "env": {
        "VK_ADS_TOKEN": "ваш_токен"
      }
    }
  }
}

If Edit Config is unavailable, edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows.

For all projects, create ~/.cursor/mcp.json; for the current project only — .cursor/mcp.json:

{
  "mcpServers": {
    "vk-ads": {
      "command": "npx",
      "args": ["-y", "mcp-vk-ads@latest"],
      "env": {
        "VK_ADS_TOKEN": "ваш_токен"
      }
    }
  }
}

Cursor documentation

Open the command palette and run MCP: Open User Configuration. Add to mcp.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": "Access-токен VK Ads",
      "password": true
    }
  ]
}

Check the launch with the MCP: List Servers command.

VS Code documentation

What you can delegate

Understand spend and results

• "Show spend, impressions, clicks, and CTR by campaigns for the last 7 days."

• "Which ads spend the most and bring no results?"

• "Compare ad groups within this campaign by spend and clicks."

Understand why ads aren't showing

• "Show the status, delivery, and moderation of all ads in this group."

• "Which campaigns are currently paused?"

• "Find ads that didn't pass moderation."

Prepare changes to ads

• "Create a text campaign with a daily budget of 5,000 rubles."

• "Change the daily budget of this group to 1,500 rubles."

• "Pause ad 12345."

Such commands change the live account. Before calling, make sure the assistant correctly identified the campaign, group, ad, and amount.

Find data for configuration

• "Show the balance and currency of my account."

• "How many API requests are left?"

• "Find the region ID for Moscow for targeting."

How VK Рекламы objects work

An object has three different states. status can be changed: active, blocked, or deleted. delivery and moderation_status only explain why an object is shown or not; they cannot be changed directly.

What can change data

Typed tools for creating, updating, and changing status have no internal confirmWrite parameter. How the AI app requests confirmation depends on its settings. After a network error or 5xx, don't blindly repeat creation: the operation may have already applied; first check the list of objects.

How to get a token

The token is issued by the VK Ads account:

1. In ads.vk.com, open Settings → API Access and create an app. Save client_id and client_secret. If the section is unavailable, request API access from VK Ads support.

2. Exchange them for an account access token:

   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

3. Take access_token from the response and save it as VK_ADS_TOKEN.

The token grants access to the advertising account, including the ability to spend budget, and is stored in plain text in the MCP client configuration. Treat it like a password. If the API responds with invalid_token, issue and provide a new token.

For agencies working with client accounts, the authorization_code flow is needed — see the VK Ads API documentation.

Configuration

Data, limits, and background operation

• Pages and large accounts. One list page contains up to 250 objects. With autoPaginate, the server returns no more than 1,000 objects and marks an incomplete result with the _truncated field.

• API limits. The get_throttling tool shows the current remaining limits. Check it before mass operations.

• Request retries. Timeout for one request is 60 seconds. The server makes up to three retries: for any method on 429, and for reads also on network error, timeout, and 5xx. The delay respects Retry-After and does not exceed 30 seconds.

• No background monitoring. The server runs when the AI app calls it. If the app supports scheduled tasks, you can set up periodic requests for statistics or statuses there.

• Anonymous telemetry. By default, the server sends a random installation ID, event or tool name, server version, Node.js, OS, and AI client. It does not include the token, account data, tool arguments, your messages, or environment variable values. Disable it for Ask Ads MCP servers: ASKADS_TELEMETRY=0.

Technical documentation

• MCP capabilities catalog — pages on user tasks for each tool.

• All tools and parameters

• Development documentation

• Package on npm

• VK Ads API documentation

Support

Found a bug or missing a scenario? Create an issue or write to Telegram.