Skip to main content
Glama
yandex-direct-mcp

yandex-direct-mcp

by iarbor04

yandex-direct-mcp

MCP-Server für Yandex Direct API v5. Verbindet ein Werbekonto mit einem KI-Agenten (Claude Code, Cursor und jedem anderen MCP-Client): Die Aufgabe wird als normaler Text gestellt, der Agent sammelt selbst die nötigen API-Aufrufe und wertet die Antwort aus.

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

Ohne Abhängigkeiten: eine Datei auf Node.js, stdio-Transport, Anfragen über eingebautes fetch.

  • Token wird lokal gespeichert in einer Datei mit Rechten 600 und geht nirgendwohin außer an api.direct.yandex.com.

  • Änderungen nur mit Bestätigung. Der MCP-Client fragt für jeden Aufruf um Erlaubnis; zusätzlich gibt es einen „Nur-Lesen“-Modus, der ändernde Methoden auf Serverebene blockiert.

  • Vollständige API, keine Teilmenge. Das universelle Werkzeug direct_call deckt alle v5-Dienste ab – von campaigns bis keywordsresearch.

Was man machen kann

Analytik. Berichte zu jedem Segment und Zeitraum: Kampagnen, Gruppen, Anzeigen, Schlüsselphrasen, Suchanfragen, Geo, Geräte, Tageszeit, Geschlecht und Alter. Ausgaben, Klicks, CTR, CPC, Conversions, CPA, Periodenvergleich. Analyse von Suchanfragen auf Müll, Suche nach Phrasen mit Ausgaben ohne Conversions.

Verwaltung. Erstellung und Bearbeitung von Kampagnen, Gruppen, Anzeigen, Schlüsselphrasen. Gebote und Tagesbudgets – auch paketweise, nach Regel („CPA über 2000 ₽ → Gebot um 20% senken“). Minuswörter, Aktivierung und Stopp, Einreichung zur Moderation, Gebotskorrekturen nach Geo, Geräten und Zielgruppen, Retargeting.

Semantik. Prüfung der Häufigkeit von Phrasen (keywordsresearch), Verzeichnisse der Regionen und Zeitzonen (dictionaries).

Regelmäßige Aufgaben. Morgenübersicht der Ausgaben von gestern, wöchentliche Analyse der Suchanfragen, Benachrichtigung bei Überausgaben – wenn der MCP-Client Zeitpläne kann.

Detaillierte Szenarien mit Beispielanfragen: docs/usage.md.

Related MCP server: Yandex MCP Server

Anforderungen

  • Node.js 18 oder neuer (eingebautes fetch erforderlich).

  • Yandex-Direct-Konto.

  • Registrierte Anwendung auf oauth.yandex.ru mit genehmigtem Antrag auf API-Zugriff. Das ist die größte Hürde und dauert von einer Stunde bis zu drei Tagen – beginne damit: docs/registration.md.

Installation

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

Keine Abhängigkeiten, npm install ist nicht nötig.

Claude Code:

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

Cursor, Windsurf und andere Clients mit JSON-Konfiguration:

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

Die Werkzeuge erscheinen beim Start des Clients – nach dem Hinzufügen des Servers starte die Sitzung neu.

Autorisierung

Die Reihenfolge ist wichtig. Wenn du es nicht in dieser Reihenfolge machst, erhältst du Fehler 58 und verlierst Zeit – wir haben sie verloren.

1. Antrag auf API-Zugriff

Du registrierst eine Anwendung auf oauth.yandex.ru und reichst einen Antrag in der Direct-Oberfläche ein: „Meine Anträge“. Die Prüfung erfolgt an Werktagen in Russland von 10:00 bis 19:00 Uhr, von einer Stunde bis zu drei Tagen, in Spitzenzeiten bis zu sieben Tagen.

Was man in das Formular schreibt (fertige Texte für alle Felder, einschließlich Beschreibung des Interaktionsschemas und Diagramm) – docs/registration.md.

Ohne genehmigten Antrag funktioniert nicht einmal die Sandbox. Getestet: api-sandbox.direct.yandex.com liefert denselben Fehler 58 wie die Produktions-API. Ein Debuggen „vorerst mit Testdaten“ ist nicht möglich.

2. Token

./save-token.sh <CLIENT_ID>

Das Skript zeigt den Autorisierungslink, wartet, bis du die Adresszeile nach der Weiterleitung einfügst (Eingabe verborgen – weder URL noch Token gelangen in die Shell-Historie), extrahiert access_token, legt es in ~/.config/yandex-direct/token mit Rechten 600 ab und führt sofort eine Zugriffsprüfung durch.

<CLIENT_ID> – die ID der Anwendung, für die der Antrag genehmigt wurde. Das Skript merkt sie sich in config.json, danach kann man es ohne Argument ausführen.

Manuell dasselbe: https://oauth.yandex.ru/authorize?response_type=token&client_id=<CLIENT_ID> öffnen, das Token aus der Adresszeile nach #access_token= (bis &) entnehmen und in die Datei legen.

3. Prüfung

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

Oder frag einfach den Agenten: „Prüfe den Zugriff auf Direct“. Eine erfolgreiche Antwort zeigt Login, Kontowährung und Punktestand.

Stolpersteine, auf die wir gestoßen sind

Symptom

Ursache

Was tun

error 58 – „Unvollständige Registrierung“, obwohl der Antrag genehmigt wurde

Token wurde unter einer anderen Anwendung erhalten, nicht der, für die der Antrag genehmigt wurde. Leicht zu erwischen, wenn es mehrere Anwendungen gibt

Öffne den genehmigten Antrag, vergleiche die Client-ID, erhalte das Token genau unter dieser

error 58 in der Sandbox

Die Sandbox erfordert ebenfalls einen genehmigten Antrag

Auf Genehmigung warten, es gibt keinen Umweg

Erneute Autorisierung gibt dasselbe Token zurück

Yandex gibt das bereits ausgestellte Token zurück, solange der Zugriff für die Anwendung nicht widerrufen wurde

Zugriff auf id.yandex.ru/personal/data-access widerrufen, dann erneut autorisieren

error 53 – „Ungültiges OAuth-Token“

Token wurde widerrufen, ist abgelaufen oder mit Abschneiden kopiert

Erneut über ./save-token.sh erhalten

clients.get antwortet, aber campaigns.get gibt eine leere Liste zurück

Token wurde unter einem Login ausgestellt, in dem es keine Kampagnen gibt

Token unter dem richtigen Login erhalten. Kein erneuter Antrag nötig: Er ist für die Anwendung genehmigt, nicht für den Benutzer

Antrag muss nach Neuerstellung der Anwendung erneut eingereicht werden

Die Genehmigung ist an die Client-ID gebunden, nicht an das Konto

Die genehmigte Anwendung nicht löschen. Falls gelöscht – neuer Antrag, in der Beschreibung auf die frühere Client-ID verweisen

Separat: Das Token darf nicht in den Chat des Agenten eingefügt werden – es bleibt in der Verlaufshistorie. Dafür gibt es save-token.sh mit versteckter Eingabe. Falls du es doch eingefügt hast – widerrufe den Zugriff auf id.yandex.ru/personal/data-access und erhalte ein neues.

Werkzeuge

Werkzeug

Zweck

direct_status

Ob ein Token vorhanden ist, welche Umgebung, ob der Zugriff aktiv ist (Test-clients.get), Punktestand. Token wird nicht offengelegt

direct_reference

Spickzettel: Dienste, Methoden, Beispiele für params, Berichtstypen, Gebotseinheiten, Limits

direct_call

Universeller Aufruf POST /json/v5/{service} mit Body {method, params}

direct_report

Reports-API: sendet ReportDefinition, wartet auf Bereitschaft (Codes 201/202), gibt TSV zurück

Konfiguration

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

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

Das Token wird bei jedem Aufruf gelesen – nach dem Ersetzen muss der Server nicht neu gestartet werden.

Umgebungsvariable

Bedeutung

YANDEX_DIRECT_TOKEN

Token direkt, hat Vorrang vor Dateien

YANDEX_DIRECT_CLIENT_LOGIN

Client-Login für Agenturkonto (Header Client-Login)

YANDEX_DIRECT_SANDBOX=1

Mit der Sandbox arbeiten

YANDEX_DIRECT_READONLY=1

add, update, delete, suspend, resume, moderate, set blockieren

YANDEX_DIRECT_CONFIG_DIR

Anderes Konfigurationsverzeichnis

Reihenfolge der Tokensuche: YANDEX_DIRECT_TOKEN → config.json → ~/.config/yandex-direct/token.

Limits und Kosten

Jeder Aufruf verbraucht Punkte (Units); der Rest kommt im Antwort-Header und wird im Kopf des Ergebnisses gedruckt. Ein normaler get – etwa 10 Punkte, Berichte sind teurer. Das Tageslimit hängt vom Konto ab (bei einem normalen Kunden – etwa 160.000, für Live-Arbeit mit Reserve).

Die Methode get liefert maximal 10.000 Objekte auf einmal – danach seitenweise über LimitOffset. Gebote werden in Mikroeinheiten angegeben: 30000000 = 30 ₽. Der ReportName eines Berichts muss eindeutig sein, sonst gibt Direct den zuvor erstellten Bericht zurück.

Interaktionsschema

Interaktionsschema mit der Yandex-Direct-API

Quelle: docs/scheme.html – nützlich, falls du eine eigene Version des Bildes für den Antrag benötigst.

Lizenz

MIT – siehe 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.

    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
      920 npm
      4
      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