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 Direct 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 접근을 확인해줘"라고 물어보면 된다. 성공적인 응답은 로그인, 계정 통화 및 잔여 포인트를 표시한다.

우리가 겪은 함정

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

도구

구성

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

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

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

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

한도 및 비용

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

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

상호작용 다이어그램

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

라이선스

MIT — LICENSE 참조.