yandex-direct-mcp
yandex-direct-mcp
Яндекс Директ 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は v5 のすべてのサービス (campaignsからkeywordsresearchまで) をカバーします。
できること
分析。 任意の切り口と期間のレポート: キャンペーン、グループ、広告、キーフレーズ、検索クエリ、地域、デバイス、時間帯、性別、年齢。支出、クリック、CTR、CPC、コンバージョン、CPA、期間比較。検索クエリのゴミ分析、コンバージョンなしの支出フレーズの検索。
管理。 キャンペーン、グループ、広告、キーフレーズの作成と編集。入札単価と日次予算 — バッチ処理やルールによる設定も可能 (「CPA が 2000 ₽ を超える → 入札単価を 20% 削減」)。マイナスキーワード、有効化と停止、モデレーション送信、地域・デバイス・オーディエンス別の入札調整、リターゲティング。
セマンティクス。 フレーズの頻度確認 (keywordsresearch)、地域とタイムゾーンの辞書 (dictionaries)。
定期的なタスク。 昨日の支出の朝のサマリー、毎週の検索クエリ分析、過剰支出の通知 — MCP クライアントがスケジュールをサポートしている場合。
詳細なシナリオとリクエスト例: docs/usage.md。
Related MCP server: Yandex MCP Server
要件
Node.js 18 以降 (組み込みの
fetchが必要)。Яндекс Директа アカウント。
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 もトークンもシェルの履歴に残りません)。access_token を抽出し、~/.config/yandex-direct/token に権限 600 で保存し、すぐにアクセスチェックを実行します。
<CLIENT_ID> — 申請が承認されたアプリケーションの 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 へのアクセスを確認して」と尋ねるだけです。成功した応答には、ログイン、アカウントの通貨、残りのポイントが表示されます。
私たちが踏んだ落とし穴
症状 | 原因 | 対処 |
| トークンが申請が承認されたアプリケーションとは別のアプリケーションで取得された。複数のアプリケーションがあると簡単に遭遇する | 承認された申請を開き、Client ID を確認し、そのアプリケーションでトークンを取得する |
サンドボックスでの | サンドボックスも承認された申請が必要 | 承認を待つしかない、回避策はない |
再認証で同じトークンが返される | アプリへのアクセスが取り消されるまで、Yandex は既に発行されたトークンを返す | id.yandex.ru/personal/data-access でアクセスを取り消し、再認証する |
| トークンが取り消された、期限切れ、または切り詰めてコピーされた |
|
| トークンがキャンペーンのないログインで発行された | 必要なログインでトークンを取得する。再申請は不要: 申請はユーザーではなくアプリケーションに対して承認されている |
アプリケーションを再作成した後、申請を再提出する必要がある | 承認はアカウントではなく Client ID に紐付いている | 承認されたアプリケーションを削除しない。削除した場合は新しい申請を行い、説明に以前の Client ID を記載する |
別途: トークンをエージェントのチャットに貼り付けてはいけません — 会話履歴に残ります。そのため、save-token.sh は非表示入力になっています。どうしても貼り付けた場合は、id.yandex.ru/personal/data-access でアクセスを取り消し、新しいトークンを取得してください。
ツール
ツール | 目的 |
| トークンの有無、環境、アクセスが有効か (テスト |
| チートシート: サービス、メソッド、 |
| 汎用呼び出し |
| Reports API: ReportDefinition を送信し、準備完了を待ち (コード 201/202)、TSV を返す |
設定
~/.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 を参照。
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