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 Direct 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

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

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.

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

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

Lizenz

MIT – siehe LICENSE.