VK 광고 MCP

VK 광고 MCP는 AI 애플리케이션을 VK Ads 광고 계정에 연결합니다. 예산을 낭비하면서 성과가 없는 캠페인을 확인하고, 그룹과 광고를 비교하고, 새 캠페인을 준비하거나 입찰가를 변경할 수 있습니다. 계정의 여러 섹션을 수동으로 이동하는 것과 달리, 어시스턴트는 캠페인, 통계, 잔액, 상태를 하나의 대화에서 대조합니다.

• 18가지 도구. 캠페인, 그룹, 광고, 통계, 잔액, API 한도, 지역 및 API 범용 요청.

• 실시간 광고. 입찰가, 예산, 지출이 광고 계정의 통화로 표시됩니다 — 마이크로 단위 환산 없이.

• 전체 계층 구조. 캠페인(ad_plan) → 그룹(ad_group) → 광고(banner).

• 먼저 분석. 목록, 보고서, 잔액, 상태는 읽기 전용으로만 제공됩니다.

• 변경은 실계정에서 적용. 생성, 업데이트, 상태 변경 작업은 즉시 적용됩니다. VK Ads에는 샌드박스가 없습니다.

안전한 요청부터 시작하세요:

내 VK 광고 계정의 캠페인과 지난주 광고 그룹별 지출을 보여줘.

서버 연결 · 시나리오 보기 · 기술 문서 열기

1분 만에 작동 확인

Related MCP server: vk-ads-mcp

목차

• 빠른 시작

• 무엇을 맡길 수 있나요

• VK 광고 객체 구조

• 데이터를 변경할 수 있는 작업

• 토큰 받는 방법

• 설정

• 데이터, 한도 및 백그라운드 작업

• 기술 문서

• 지원

빠른 시작

Node.js 20 이상과 VK Ads access 토큰이 필요합니다. 서버는 npx로 실행되므로 패키지를 별도로 설치할 필요가 없습니다.

1. 토큰을 받고 AI 애플리케이션에 서버를 추가하세요 — 아래 5개 애플리케이션에 대한 안내가 있습니다.

2. "내 VK 광고 계정의 캠페인과 지난주 광고 그룹별 지출을 보여줘"라고 물어보세요.

앱 인터페이스를 통해:

1. Settings → Plugins → MCP servers를 엽니다.

2. Add server를 클릭합니다.

3. 실행 명령 npx -y mcp-vk-ads@latest와 자신의 토큰이 담긴 환경 변수 VK_ADS_TOKEN을 추가합니다.

명령줄을 통해:

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

연결을 확인하세요:

codex mcp list

Codex 공식 안내

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

서버를 확인하세요:

claude mcp list

Claude Code 문서

Settings → Developer → Edit Config를 열고 claude_desktop_config.json에 서버를 추가하세요:

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

Edit Config를 사용할 수 없다면 macOS에서는 ~/Library/Application Support/Claude/claude_desktop_config.json, Windows에서는 %APPDATA%\Claude\claude_desktop_config.json을 직접 편집하세요.

모든 프로젝트에 적용하려면 ~/.cursor/mcp.json을 만들고, 현재 프로젝트에만 적용하려면 .cursor/mcp.json을 만드세요:

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

Cursor 문서

명령 팔레트를 열고 MCP: Open User Configuration을 실행하세요. 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
    }
  ]
}

MCP: List Servers 명령으로 실행을 확인하세요.

VS Code 문서

무엇을 맡길 수 있나요

지출과 성과 파악하기

• "최근 7일간 캠페인별 지출, 노출, 클릭, CTR을 보여줘."

• "지출이 가장 많고 성과가 없는 광고는 무엇인가요?"

• "이 캠페인 내 광고 그룹을 지출과 클릭 기준으로 비교해줘."

광고가 게재되지 않는 이유 이해하기

• "이 그룹의 모든 광고 상태, 게재 상태, 검수 상태를 보여줘."

• "현재 중지된 캠페인은 무엇인가요?"

• "검수를 통과하지 못한 광고를 찾아줘."

광고 변경 준비하기

• "일일 예산 5,000루블의 텍스트 캠페인을 만들어줘."

• "이 그룹의 일일 예산을 1,500루블로 변경해줘."

• "광고 12345를 중지해줘."

이러한 명령은 실계정을 변경합니다. 호출 전에 어시스턴트가 캠페인, 그룹, 광고, 금액을 올바르게 식별했는지 확인하세요.

설정에 필요한 데이터 찾기

• "내 계정의 잔액과 통화를 보여줘."

• "API 요청이 얼마나 남았나요?"

• "타겟팅용 모스크바 지역 ID를 찾아줘."

VK 광고 객체 구조

객체에는 세 가지 서로 다른 상태가 있습니다. status는 변경할 수 있습니다: active, blocked 또는 deleted. delivery와 moderation_status는 객체가 게재되는지 여부를 설명할 뿐이며 직접 변경할 수 없습니다.

데이터를 변경할 수 있는 작업

타입이 지정된 생성, 업데이트, 상태 변경 도구에는 내부 confirmWrite 매개변수가 없습니다. AI 애플리케이션이 확인을 요청하는 방식은 해당 앱의 설정에 따라 다릅니다. 네트워크 오류나 5xx 이후에는 맹목적으로 생성을 반복하지 마세요. 작업이 이미 적용되었을 수 있으므로 먼저 객체 목록을 확인하세요.

토큰 받는 방법

토큰은 VK Ads 계정에서 발급합니다:

1. ads.vk.com에서 설정 → API 액세스를 열고 애플리케이션을 만드세요. client_id와 client_secret을 저장하세요. 섹션을 사용할 수 없다면 VK Ads 지원팀에 API 액세스를 요청하세요.

2. 이를 계정 access 토큰으로 교환하세요:

   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. 응답에서 access_token을 가져와 VK_ADS_TOKEN으로 저장하세요.

토큰은 예산을 지출할 수 있는 권한을 포함해 광고 계정에 대한 액세스를 제공하며 MCP 클라이언트 구성에 평문으로 저장됩니다. 비밀번호처럼 취급하세요. API가 invalid_token으로 응답하면 새 토큰을 발급하여 지정하세요.

클라이언트 계정을 관리하는 에이전시는 authorization_code 시나리오가 필요합니다 — VK Ads API 문서를 참조하세요.

설정

데이터, 한도 및 백그라운드 작업

• 페이지 및 대규모 계정. 목록 페이지 하나에는 최대 250개의 객체가 포함됩니다. autoPaginate 시 서버는 최대 1,000개의 객체를 반환하며 불완전한 결과는 _truncated 필드로 표시합니다.

• API 한도. get_throttling 도구는 현재 남은 한도를 보여줍니다. 대량 작업 전에 확인하세요.

• 요청 재시도. 단일 요청 타임아웃은 60초입니다. 서버는 최대 3회 재시도합니다: 모든 메서드에서 429 발생 시, 읽기의 경우 네트워크 오류, 타임아웃, 5xx 발생 시에도 재시도합니다. 지연 시간은 Retry-After를 고려하며 30초를 초과하지 않습니다.

• 백그라운드 모니터링 없음. 서버는 AI 애플리케이션이 호출할 때만 작동합니다. 애플리케이션이 예약 작업을 지원한다면 주기적인 통계 또는 상태 요청을 설정할 수 있습니다.

• 익명 텔레메트리. 기본적으로 서버는 무작위 설치 ID, 이벤트 또는 도구 이름, 서버 버전, Node.js, OS, AI 클라이언트 버전을 전송합니다. 토큰, 계정 데이터, 도구 인수, 사용자 메시지, 환경 변수 값은 포함되지 않습니다. Ask Ads MCP 서버에서 비활성화하려면: ASKADS_TELEMETRY=0.

기술 문서

• MCP 기능 카탈로그 — 각 도구의 사용자 작업별 페이지.

• 모든 도구 및 매개변수

• 개발 문서

• npm 패키지

• VK Ads API 문서

지원

오류를 발견했거나 시나리오가 부족한가요? issue를 생성하거나 Telegram으로 문의하세요.