Yandex Direct MCP

Yandex Direct MCP는 AI 애플리케이션을 Yandex Direct 광고 계정에 연결합니다. 자연어로 광고 예산이 어디에 사용되는지 물어보고, 캠페인·광고·키워드 문구를 대조한 다음, 계정의 여러 섹션을 오가며 전환할 필요 없이 필요한 변경 사항을 준비하거나 적용할 수 있습니다. 연결은 대화 중에 바로 시작됩니다. 토큰을 미리 만들거나 구성을 편집할 필요가 없습니다.

• 44개 도구. 캠페인, 그룹, 광고, 키워드 문구, 입찰가, 조정, 확장, 통계, 잔액, 참고 자료 및 계정 연결을 대화 중에 바로 처리합니다.

• 두 가지 연결 방식. URL 기반 원격 서버는 토큰을 수동으로 받을 필요가 없고 데이터만 읽습니다. npx를 통한 로컬 연결은 계정에 대한 전체 액세스를 제공합니다.

• 채팅에서 연결. Yandex가 로그인 페이지를 엽니다. 채팅에서 코드를 받은 후 바로 광고 작업을 시작할 수 있으며, 액세스는 자동으로 갱신됩니다.

• 알기 쉬운 금액 표시. 편리한 도구에서 예산, 입찰가, 잔액이 API의 마이크로 단위가 아닌 계정 통화로 표시됩니다.

• 실제 광고. 로컬 변경 사항은 실제 운영 계정에 적용되며 지출에 영향을 미칠 수 있습니다. 테스트 환경에서 작업하려면 Yandex Direct 샌드박스가 있습니다.

첫 메시지로 시도해 보세요:

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

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

1분 만에 작동 확인하기

사용자: Yandex Direct를 연결해 줘.

어시스턴트: Yandex 로그인 링크를 제공합니다. 원하는 광고 계정에 액세스할 수 있는 계정으로 링크를 열고, 액세스를 확인한 후 표시된 코드를 보내 주세요.

사용자: Yandex 페이지에서 코드를 보냅니다.

어시스턴트: Direct를 연결하고 계정을 표시합니다. 애플리케이션을 다시 시작할 필요가 없습니다.

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

어시스턴트: 캠페인을 찾고, 광고 그룹별 보고서를 작성한 후 계정 통화로 지출을 표시합니다.

Related MCP server: Yandex Direct MCP Server

목차

• 빠른 시작

• 맡길 수 있는 작업

• 작동 방식

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

• 연결 및 설정

• 데이터 및 원격 측정

• 제한 사항

• 기술 문서

• 지원

빠른 시작

1. 아래 지침에 따라 연결 방식을 선택하고 AI 애플리케이션에 서버를 추가합니다.

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

토큰을 직접 받지 않는 분석 — URL 방식

원격 서버 https://mcp.askads.ru/mcp는 URL로 MCP를 지원하는 애플리케이션을 통해 연결됩니다. 브라우저에서 Yandex에 로그인하고 액세스를 확인하세요. 토큰을 구성에 전달할 필요가 없습니다. 이 방식은 읽기 전용입니다 — 통계, 감사, 객체 조회용이며 광고 설정을 변경하지 않습니다.

Claude Code에서는 다음 명령으로 추가할 수 있습니다:

claude mcp add --transport http yandex-direct https://mcp.askads.ru/mcp

연결 후 /mcp를 열고 인증을 진행하세요. HTTP MCP를 지원하는 다른 애플리케이션에서는 애플리케이션 인터페이스를 통해 동일한 URL을 추가하세요.

전체 액세스 — npx를 통한 로컬 연결

객체를 생성하고 수정하려면 Node.js 20+가 필요합니다. npx는 첫 실행 시 서버를 다운로드하므로 패키지를 별도로 설치할 필요가 없습니다. 토큰을 미리 받을 필요도 없습니다 — 연결은 대화 중에 바로 시작됩니다:

1. AI 애플리케이션에 서버를 추가하세요 — 아래에 Codex용 예시가 열려 있고, 다른 애플리케이션은 접이식 지침에 모아 두었습니다.

2. "Yandex Direct를 연결해 줘"라고 입력하세요 — 어시스턴트가 Yandex 로그인을 안내하고 계정을 표시합니다.

CI 및 에이전트 설치용 — 준비된 토큰과 YANDEX_DIRECT_LOGIN, 연결 및 설정 참조.

애플리케이션 인터페이스로:

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

2. Add server를 클릭합니다.

3. 실행 명령 npx -y mcp-yandex-direct@latest를 추가합니다.

명령줄로:

codex mcp add yandex-direct -- npx -y mcp-yandex-direct@latest

연결 확인:

codex mcp list

Codex 공식 지침

claude mcp add --transport stdio --scope user yandex-direct -- npx -y mcp-yandex-direct@latest

연결 확인: claude mcp list.

Settings → Developer → Edit Config를 열고 claude_desktop_config.json에 추가합니다:

{
  "mcpServers": {
    "yandex-direct": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-direct@latest"]
    }
  }
}

Developer 섹션이 없으면 파일을 수동으로 엽니다: macOS — ~/Library/Application Support/Claude/claude_desktop_config.json, Windows — %APPDATA%\Claude\claude_desktop_config.json. Claude Desktop을 다시 시작합니다.

~/.cursor/mcp.json을 열어 모든 프로젝트에서 서버를 연결하거나, 특정 프로젝트의 .cursor/mcp.json을 엽니다. 다음을 추가합니다:

{
  "mcpServers": {
    "yandex-direct": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-direct@latest"]
    }
  }
}

명령 팔레트에서 MCP: Open User Configuration을 실행합니다. 열린 mcp.json에 서버를 추가합니다:

{
  "servers": {
    "yandex-direct": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yandex-direct@latest"]
    }
  }
}

저장 후 MCP: List Servers를 실행하고 목록에서 서버를 시작합니다.

맡길 수 있는 작업

예산 사용 확인

• "지난주에 가장 많은 비용을 지출한 캠페인은 무엇인가요?"

• "노출과 클릭은 받지만 전환을 만들지 못하는 광고는 무엇인가요?"

• "한 달간 캠페인별 지출, CTR, 평균 클릭 단가를 비교해 줘."

• "계정 잔액과 API 일일 할당량 잔여량을 보여줘."

개선 포인트 찾기

• "예산을 소비하지만 클릭을 만들지 못하는 키워드 문구는 무엇인가요?"

• "현재 중지되었거나 검토를 통과하지 못한 그룹과 광고는 무엇인가요?"

• "모바일 기기에 적용 중인 입찰가 조정을 확인해 줘."

• "이 캠페인에 어떤 빠른 링크와 추가 정보가 있나요?"

변경 사항 준비

• "CTR이 높은 문구에 대한 새 입찰가를 제안하고 적용 전 변경 사항을 보여줘."

• "캠페인에 이 주제에 대한 제외 키워드가 있는지 확인하고 목록을 준비해 줘."

• "모스크바용 새 텍스트 캠페인의 매개변수를 수집해 줘: 예산, 그룹, 키워드 문구, 광고."

명시적 작업 실행

• "이 키워드 문구를 그룹 123에 추가하고 입찰가를 45₽로 설정해 줘."

• "광고 456을 일시 중지해 줘."

• "이미지가 있는 페이지를 광고 라이브러리로 보내 줘."

작동 방식

광고는 일반적으로 세 가지 수준으로 구성됩니다: 캠페인 → 광고 그룹 → 광고. 그룹에는 키워드 문구, 노출 설정, 입찰가 조정이 있습니다. 광고에는 빠른 링크, 추가 정보, 명함, 이미지가 있을 수 있습니다.

서버는 이러한 객체를 함께 볼 수 있도록 도와줍니다: 캠페인 지출을 그룹 통계, 키워드 문구, 광고와 연결합니다. 새 캠페인과 광고는 텍스트 유형만 만들 수 있습니다. 다른 유형의 캠페인은 읽기, 이름 변경, 예산 변경, 중지, 보관, ID로 삭제가 가능합니다.

통계는 즉시 생성되지 않습니다: get_statistics는 Reports 서비스에서 보고서를 시작하고 완료를 기다립니다. 큰 목록은 autoPaginate가 결과 페이지를 자동으로 순회합니다.

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

URL 기반 원격 서버는 데이터만 읽습니다. npx를 통한 로컬 서버는 실제 운영 광고 계정을 변경할 수 있습니다:

도구는 AI 애플리케이션에 읽기, 쓰기, 잠재적으로 되돌릴 수 없는 작업 레이블을 전달합니다. 애플리케이션은 확인을 표시할 수 있지만 그 동작은 클라이언트에 따라 다릅니다. 직접 API 요청은 confirmWrite=true 없이는 추가로 쓰기를 수행하지 않습니다. 광고를 변경하려면 명시적인 요청이 필요합니다.

연결 및 설정

일반적인 사용에서는 토큰을 미리 받을 필요가 없습니다:

1. 채팅에서 Yandex Direct 연결을 요청하세요.

2. 원하는 광고 계정에 액세스할 수 있는 계정으로 Yandex OAuth 링크를 여세요.

3. 액세스를 확인하고 표시된 코드를 채팅으로 보내세요. 이제 광고 작업을 할 수 있습니다: 클라이언트를 다시 시작할 필요도, 구성을 수정할 필요도 없습니다.

이후 연결은 자동으로 유지됩니다: 액세스는 자동으로 갱신되며 1년 후에도 끊기지 않습니다. 상태 확인은 "연결 상태를 보여줘", 해제는 "Direct를 연결 해제해 줘"라고 요청하세요. 발급된 액세스는 Yandex ID에서 취소할 수 있습니다.

대화가 없는 CI 및 자동 설치의 경우 환경 변수를 통한 설정이 가능합니다:

YANDEX_DIRECT_TOKEN용 준비된 토큰은 원하는 계정에 액세스할 수 있는 계정으로 로그인하여 링크에서 받을 수 있습니다:

Yandex Direct 토큰 받기

채팅, 저장소 및 스크린샷에 토큰을 게시하지 마세요. 토큰은 광고 계정에 대한 액세스 권한을 부여하며, 예산에 영향을 줄 수 있는 작업을 포함합니다.

데이터 및 원격 분석

기본적으로 서버는 익명의 기술 이벤트를 전송합니다: 무작위 설치 식별자, 호출된 도구의 이름, 서버, AI 애플리케이션, Node.js 및 운영 체제의 버전입니다. 이는 서버의 어떤 부분이 사용되고 있는지, 실행 중 문제가 발생하는지 파악하기 위한 것입니다. Yandex 토큰, 광고 계정 데이터, 도구 인수, 요청 텍스트, 환경 변수의 값과 이름은 전송되지 않습니다.

Ask Ads MCP 서버의 원격 분석을 비활성화하려면 환경 변수를 설정하세요:

ASKADS_TELEMETRY=0

제한 사항

• 일일 API 할당량. 각 호출은 Units를 소비합니다. get_quota 도구는 오늘 지출된 금액, 남은 금액 및 사용 가능한 금액을 표시합니다.

• 보고서 제한. Yandex 보고서에는 일일 볼륨 및 수량에 대한 자체 제한이 있으며, Reports 서비스에서 보고서가 준비될 때까지 기다려야 합니다.

• 대용량 목록. 자동 페이지네이션 중 내부 한도에 도달하면 서버는 결과를 숨기지 않고 명시적으로 불완전한 것으로 표시합니다.

• 일시적 오류. 서버는 빈도 제한 시 최대 3회 재시도합니다. 네트워크 및 서버 오류는 변경 사항을 중복하지 않도록 읽기 전용으로만 자동 재시도됩니다.

• 실제 계정. 로컬 변경 사항은 실제 광고 계정에 적용되며 지출에 영향을 미칠 수 있습니다. 테스트에는 샌드박스(YANDEX_DIRECT_SANDBOX=true)를 사용하세요.

• 상시 모니터링 없음. 서버는 AI 애플리케이션에서 호출하는 동안에만 작동합니다. 애플리케이션이 정기 작업을 지원하는 경우, 필요한 지표를 확인하기 위해 주기적 요청을 설정할 수 있습니다.

기술 문서

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

• 모든 도구 — 각 도구의 매개변수, 응답 및 한계.

• 개발 — 프로젝트 구조 및 소스 코드 작업.

• Yandex Direct API — API 및 제한 사항에 대한 원본 소스.

• npm 패키지 — 게시된 서버 버전.

지원

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