yandex-direct-mcp
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_calldeckt alle v5-Dienste ab – voncampaignsbiskeywordsresearch.
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
fetcherforderlich).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-mcpKeine 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.jsOder 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 |
| 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 |
| 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 |
| Token wurde widerrufen, ist abgelaufen oder mit Abschneiden kopiert | Erneut über |
| 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 |
| Ob ein Token vorhanden ist, welche Umgebung, ob der Zugriff aktiv ist (Test- |
| Spickzettel: Dienste, Methoden, Beispiele für |
| Universeller Aufruf |
| 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 |
| Token direkt, hat Vorrang vor Dateien |
| Client-Login für Agenturkonto (Header |
| Mit der Sandbox arbeiten |
|
|
| 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

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 toolsdirect_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
Scored across 4 tools
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.
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.
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.
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
MCP for Yandex Direct: manage ad campaigns & analytics from Claude or ChatGPT
Review Yandex Direct reports and manage supported campaign settings in ChatGPT.
Open-source ad agent for LinkedIn Ads and Google Ads. Drafts campaigns, audiences and reports.
Google Ads for AI agents: live reports, Keyword Planner, and changes with preview, confirm and undo.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables managing Yandex Direct PPC campaigns, ad groups, ads, and keywords, plus pulling performance statistics via the Yandex Direct API v5.46920 npm4MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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
- AlicenseNot gradedqualityAmaintenanceAn MCP server that gives AI agents direct access to the Yandex Direct API to manage campaigns, groups, ads, keywords, bids, and reports via natural language.117 npm6Apache 2.0
- AlicenseAqualityDmaintenanceEnables AI assistants to manage Yandex Direct advertising campaigns, ads, keywords, and reports via natural language using the Yandex Direct API v5.21MIT