Skip to main content
Glama
yandex-direct-mcp

yandex-direct-mcp

by iarbor04

yandex-direct-mcp

Yandex Direct API v5용 MCP 서버. 광고 계정을 AI 에이전트(Claude Code, Cursor 및 기타 MCP 클라이언트)에 연결한다: 작업은 일반 텍스트로 제시되고, 에이전트가 필요한 API 호출을 직접 구성하고 응답을 분석한다.

Ты:    посмотри, куда за август ушёл бюджет и что откручивается без конверсий
Агент: [direct_report] → 12 кампаний, 340 фраз
       Расход 214 800 ₽. Кампания «Поиск / Бренд» — 38%, CPA 610 ₽.
       17 фраз потратили 31 400 ₽ при нуле конверсий — вот они, отключаем?

의존성 없음: Node.js 단일 파일, stdio 전송, 내장 fetch를 통한 요청.

  • 토큰은 로컬에 저장되며 권한 600의 파일에 보관되고 api.direct.yandex.com 외에는 어디로도 전송되지 않는다.

  • 변경 사항은 확인 후 적용. MCP 클라이언트가 각 호출에 대해 권한을 묻는다. 또한 서버 수준에서 변경 메서드를 차단하는 '읽기 전용' 모드가 있다.

  • 전체 API, 부분집합이 아님. 범용 도구 direct_call은 campaigns부터 keywordsresearch까지 v5의 모든 서비스를 포괄한다.

할 수 있는 작업

분석. 모든 기준과 기간별 보고서: 캠페인, 그룹, 광고, 키워드, 검색어, 지역, 기기, 시간대, 성별 및 연령. 지출, 클릭수, CTR, CPC, 전환, CPA, 기간 비교. 검색어의 노이즈 분석, 전환 없는 지출이 있는 키워드 찾기.

관리. 캠페인, 그룹, 광고, 키워드 생성 및 수정. 입찰가와 일일 예산 — 규칙 기반 일괄 처리 포함("CPA 2000₽ 초과 → 입찰가 20% 인하"). 마이너스 키워드, 활성화 및 중지, 검토 제출, 지역·기기·오디언스별 입찰가 조정, 리타게팅.

시맨틱. 키워드 빈도 확인(keywordsresearch), 지역 및 시간대 사전(dictionaries).

정기 작업. 전일 지출 아침 요약, 주간 검색어 분석, 초과 지출 알림 — MCP 클라이언트가 스케줄을 지원하는 경우.

요청 예시가 포함된 상세 시나리오: docs/usage.md.

Related MCP server: Yandex MCP Server

요구 사항

  • Node.js 18 이상(내장 fetch 필요).

  • Yandex Direct 계정.

  • oauth.yandex.ru에 등록된 앱 및 API 접근 승인된 신청. 이것이 가장 큰 장벽이며 1시간에서 3일이 소요된다 — 여기서 시작하라: docs/registration.md.

설치

git clone https://github.com/iarbor04/yandex-direct-mcp.git
cd yandex-direct-mcp

의존성이 없으므로 npm install은 필요 없다.

Claude Code:

claude mcp add yandex-direct --scope user -- node "$PWD/server.js"

Cursor, Windsurf 및 JSON 구성이 있는 기타 클라이언트:

{
  "mcpServers": {
    "yandex-direct": {
      "command": "node",
      "args": ["/абсолютный/путь/yandex-direct-mcp/server.js"]
    }
  }
}

도구는 클라이언트 시작 시 나타난다 — 서버 추가 후 세션을 재시작하라.

인증

순서가 중요하다. 이 순서대로 하지 않으면 오류 58을 받고 시간을 낭비하게 된다 — 우리가 겪었다.

1. API 접근 신청

oauth.yandex.ru에서 앱을 등록하고 Direct 인터페이스에서 신청을 제출한다: «Мои заявки». 검토는 러시아 평일 10:00~19:00에 이루어지며, 1시간에서 3일, 피크 기간에는 최대 7일이 소요된다.

양식에 무엇을 쓸지(상호작용 방식 설명과 다이어그램을 포함한 모든 필드용 준비된 텍스트) — docs/registration.md.

승인된 신청 없이는 샌드박스조차 작동하지 않는다. 확인됨: api-sandbox.direct.yandex.com도 운영 API와 동일한 오류 58을 반환한다. "테스트 데이터로" 디버깅하는 것은 불가능하다.

2. 토큰

./save-token.sh <CLIENT_ID>

스크립트가 인증 링크를 표시하고, 리다이렉트 후 주소 표시줄을 붙여넣을 때까지 기다린 다음(입력은 숨김 — URL도 토큰도 shell 기록에 남지 않음), access_token을 추출하여 권한 600으로 ~/.config/yandex-direct/token에 저장하고 즉시 접근 확인을 실행한다.

<CLIENT_ID> — 신청이 승인된 그 앱의 식별자. 스크립트가 이를 config.json에 기억하므로 이후에는 인자 없이 실행할 수 있다.

수동으로도 동일: https://oauth.yandex.ru/authorize?response_type=token&client_id=<CLIENT_ID>를 열고, #access_token=(부터 &까지) 뒤의 주소 표시줄에서 토큰을 가져와 파일에 저장한다.

3. 확인

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"direct_status","arguments":{}}}' \
  | node server.js

또는 에이전트에게 "Direct 접근을 확인해줘"라고 물어보면 된다. 성공적인 응답은 로그인, 계정 통화 및 잔여 포인트를 표시한다.

우리가 겪은 함정

증상

원인

해결 방법

error 58 — 신청이 승인되었는데도 "미완료 등록"

토큰이 신청이 승인된 앱이 아닌 다른 앱으로 발급됨. 앱이 여러 개면 쉽게 실수함

승인된 신청을 열고 Client ID를 확인한 후, 정확히 그 앱으로 토큰을 발급받아라

샌드박스에서 error 58

샌드박스도 승인된 신청이 필요함

승인을 기다려라, 우회 방법은 없음

재인증 시 동일한 토큰이 반환됨

앱 접근이 취소되지 않는 한 Yandex가 이미 발급된 토큰을 반환함

id.yandex.ru/personal/data-access에서 접근을 취소한 후 다시 인증하라

error 53 — "유효하지 않은 OAuth 토큰"

토큰이 취소되었거나, 만료되었거나, 잘려서 복사됨

./save-token.sh로 다시 발급받아라

clients.get은 응답하지만 campaigns.get이 빈 목록을 반환함

토큰이 캠페인이 없는 로그인으로 발급됨

올바른 로그인으로 토큰을 발급받아라. 재신청은 불필요: 신청은 사용자가 아닌 앱에 승인됨

앱 재생성 후 신청을 다시 제출해야 함

승인은 계정이 아닌 Client ID에 연결됨

승인된 앱을 삭제하지 마라. 삭제했다면 — 새 신청에서 이전 Client ID를 언급하라

별도로: 토큰을 에이전트 채팅에 붙여넣지 마라 — 대화 기록에 남는다. 이를 위해 숨김 입력 방식의 save-token.sh가 만들어진 것이다. 어쨌든 붙여넣었다면 id.yandex.ru/personal-data-access에서 접근을 취소하고 새로 발급받아라.

도구

도구

용도

direct_status

토큰 존재 여부, 환경, 접근 활성 여부(테스트 clients.get), 잔여 포인트. 토큰은 공개되지 않음

direct_reference

참고 자료: 서비스, 메서드, params 예시, 보고서 유형, 입찰가 단위, 한도

direct_call

본문 {method, params}을 사용한 범용 POST /json/v5/{service} 호출

direct_report

Reports API: ReportDefinition 전송, 준비 완료 대기(코드 201/202), TSV 반환

구성

~/.config/yandex-direct/config.json:

{
  "token": "",
  "client_id": "…",
  "client_login": "",
  "sandbox": false
}

토큰은 매 호출 시 읽힌다 — 교체 후 서버를 재시작할 필요가 없다.

환경 변수

의미

YANDEX_DIRECT_TOKEN

토큰 직접 지정, 파일보다 우선함

YANDEX_DIRECT_CLIENT_LOGIN

에이전시 계정의 클라이언트 로그인(Client-Login 헤더)

YANDEX_DIRECT_SANDBOX=1

샌드박스 사용

YANDEX_DIRECT_READONLY=1

add, update, delete, suspend, resume, moderate, set 차단

YANDEX_DIRECT_CONFIG_DIR

다른 구성 디렉터리

토큰 검색 순서: YANDEX_DIRECT_TOKEN → config.json → ~/.config/yandex-direct/token.

한도 및 비용

각 호출은 포인트(Units)를 소비한다. 잔여 포인트는 응답 헤더에 포함되며 결과 상단에 출력된다. 일반적인 get은 약 10포인트, 보고서는 더 비싸다. 일일 한도는 계정에 따라 다르다(일반 클라이언트의 경우 약 160,000, 여유 있게 실사용 가능).

get 메서드는 한 번에 최대 10,000개 객체를 반환한다 — 이후에는 LimitOffset으로 페이지네이션. 입찰가는 마이크로 단위로 지정: 30000000 = 30₽. 보고서의 ReportName은 고유해야 하며, 그렇지 않으면 Direct가 이전에 생성된 보고서를 반환한다.

상호작용 다이어그램

Yandex Direct API 상호작용 다이어그램

원본: docs/scheme.html — 신청용 이미지의 자체 버전이 필요할 때 유용하다.

라이선스

MIT — LICENSE 참조.

Available Tools

4 tools
direct_callA

Универсальный вызов Яндекс Директ API v5: POST на /json/v5/{service} с телом {method, params}. Покрывает всё управление: кампании, группы, объявления, ключевые фразы, ставки, ретаргетинг, справочники. Сначала загляни в direct_reference за именами сервисов, методов и формой params.

Inputs: method (required), service (required), params, sandbox, +1 more.

direct_referenceA

Шпаргалка по API v5: список сервисов, методов, примеры params, типы отчётов, единицы ставок и лимиты. Вызывай перед первым direct_call, чтобы не гадать с полями.

Inputs: no named parameters.

direct_reportA

Статистика через сервис Reports API v5. Принимает ReportDefinition в params, сам дожидается готовности отчёта (коды 201/202 с повторами) и возвращает TSV.

Inputs: params (required), sandbox, client_login, wait_seconds, +1 more.

direct_statusA

Проверить подключение к Яндекс Директу: найден ли токен, какая среда (боевая/песочница), доступен ли API (пробный clients.get) и сколько осталось баллов. Токен не раскрывается.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 4 tools

    Disambiguation4/5

    Each tool has a clearly distinct role: status check, generic API call, report retrieval, and API reference. There is slight overlap because direct_call could theoretically hit report services or reference data, but the descriptions clearly separate async reports and reference lookups, so an agent can reliably choose the right tool.

    Naming Consistency5/5

    All tools share the 'direct_' prefix followed by a single concise word, creating a highly predictable and consistent naming scheme. The pattern is uniform and avoids mixed conventions or vague generic names.

    Tool Count5/5

    With 4 tools, the server is intentionally compact: a generic API call handles the long tail of operations, while status, report, and reference tools cover cross-cutting concerns. This is a well-scoped count for a broad but unified API surface.

    Completeness5/5

    The generic direct_call provides full coverage of all Yandex Direct API services and methods, so no CRUD operations are missing. direct_report adds proper handling of async report generation, and direct_reference closes the discoverability gap. The set is complete for its stated purpose.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables managing Yandex Direct PPC campaigns, ad groups, ads, and keywords, plus pulling performance statistics via the Yandex Direct API v5.
      46
      641 npm
      10
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables interaction with Yandex advertising and analytics APIs (Direct, Metrika, Audience, Webmaster, AdMetrica) through MCP tools, resources, and prompts for campaign management and data retrieval.
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to manage Yandex Direct advertising campaigns, ads, keywords, and reports via natural language using the Yandex Direct API v5.
      2
      1
      MIT