Yandex Wordstat MCP

Яндекс Вордстат MCP

Яндекс Вордстат MCP は、AI アプリケーションを Yandex の検索需要統計に接続します。あるフレーズがどのくらいの頻度で検索されているか、何月に関心が高まるか、どの都市でそのトピックが人気かを尋ねると、アシスタントが Wordstat のデータを収集し、結果を説明します。サーバーは Yandex Cloud Search API を通じて動作するため、Direct 広告アカウントへのアクセスは不要です。

• 5 つのツール。 人気の検索語句や類似検索語句、検索需要の推移、地域別分布、地域ディレクトリ、API への技術的なリクエストを利用できます。
• 読み取り専用。 Wordstat API はキャンペーン、広告、キーフレーズ、その他のオブジェクトを作成しません。
• 検索需要と季節性。 人気の検索語句と地域のデータは直近 30 日分を表示します。推移は、指定した期間について日別、週別、または月別に表示できます。
• 地域とデバイス。 レポートは地域で絞り込み、パソコン、スマートフォン、タブレットでの検索需要を比較できます。
• Direct の OAuth は不要。 Search API 用の API キーと Yandex Cloud のカタログ ID が必要です。

まずは安全なリクエストを試してみましょう。

「自転車を買う」は月に何回検索されますか？ 類似する検索語句も教えてください。

サーバーを接続する · 利用シナリオを見る · 技術ドキュメントを開く

1 分で動作を確認

目次

• クイックスタート
• 依頼できること
• 検索需要データの読み方
• アクセスの取得方法
• データを変更できる操作
• データ、制限、バックグラウンドでの動作
• 技術ドキュメント
• サポート

クイックスタート

Node.js 20 以降、Search API 用の Yandex Cloud API キー、Yandex Cloud のフォルダー ID が必要です。

1. アクセス権を取得し、MCP サーバーを AI アプリに追加します。以下に 5 つのアプリの手順を記載しています。
2. 「「купить велосипед」の月間検索数と、類似する検索語を教えてください」と尋ねます。

codex mcp add yandex-wordstat \
  --env WORDSTAT_API_KEY=ваш_ключ \
  --env WORDSTAT_FOLDER_ID=ваш_folder_id \
  -- npx -y mcp-yandex-wordstat@latest

codex mcp list

claude mcp add \
  --env WORDSTAT_API_KEY=ваш_ключ \
  --env WORDSTAT_FOLDER_ID=ваш_folder_id \
  --transport stdio \
  --scope user \
  yandex-wordstat \
  -- npx -y mcp-yandex-wordstat@latest

claude mcp list

{
  "mcpServers": {
    "yandex-wordstat": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-wordstat@latest"],
      "env": {
        "WORDSTAT_API_KEY": "ваш_ключ",
        "WORDSTAT_FOLDER_ID": "ваш_folder_id"
      }
    }
  }
}

{
  "mcpServers": {
    "yandex-wordstat": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-wordstat@latest"],
      "env": {
        "WORDSTAT_API_KEY": "ваш_ключ",
        "WORDSTAT_FOLDER_ID": "ваш_folder_id"
      }
    }
  }
}

{
  "servers": {
    "yandex-wordstat": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yandex-wordstat@latest"],
      "env": {
        "WORDSTAT_API_KEY": "${input:wordstat_api_key}",
        "WORDSTAT_FOLDER_ID": "${input:wordstat_folder_id}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "wordstat_api_key",
      "description": "API-ключ Yandex Cloud",
      "password": true
    },
    {
      "type": "promptString",
      "id": "wordstat_folder_id",
      "description": "ID каталога Yandex Cloud"
    }
  ]
}

依頼できること

検索需要を調べて評価する

• 「このフレーズは月に何回検索され、どんな類似検索語がありますか？」
• 「「доставка пиццы」に関連する検索語を、検索頻度とあわせて提案してください」
• 「指定したフレーズを含む検索語と、意味的に類似する検索語を分けて表示してください」

季節性を把握する

• 「「лыжи」の年間月別需要を表示してください」
• 「このサービスの需要が増減するのは何週目ですか？」
• 「スマートフォンとパソコンでの検索語の推移を比較してください」

地域を比較する

• 「「ремонту квартир」への関心が平均を上回る都市はどこですか？」
• 「モスクワとサンクトペテルブルクの需要を比較してください」
• 「対象地域の ID を調べ、次のレポートをその地域に絞ってください」

検索需要データの読み方

top_requests には、指定したフレーズを含む人気の検索語と、意味的に近い検索語が表示されます。合計の totalCount は直近 30 日間の値です。

dynamics は、日別・週別・月別の {date, count, share} データ系列を返します。regions は直近 30 日間の需要を地域別に分布し、affinityIndex が 100% を超える場合は平均を上回る関心を示します。カウント値は文字列で返されることがあります。Yandex は大きな整数を JSON でこの形式で渡します。

1 回の呼び出しでデータを作成できるのは 1 つのフレーズだけです。キーワードが大量にある場合は、すべての検索を続けて実行するのではなく、まずリストを絞り込むことをおすすめします。Yandex Cloud Search API のクォータは、1 つのキーで共有されます。

アクセス権を取得する

1. Yandex Cloud で search-api.webSearch.user ロールを持つサービスアカウントを作成します。
2. そのアカウント用に scope yc.search-api.execute の API キーを発行します。手順は AI Studio のドキュメントに記載されています。
3. Yandex Cloud コンソールのカタログページとページの URL で、カタログ ID（folderId）を確認します。
4. キーを WORDSTAT_API_KEY、カタログを WORDSTAT_FOLDER_ID として渡します。

このサーバーは Yandex Cloud Search API v2 にアクセスします。OAuth を使う旧式の独立した Wordstat API は使用しません。API キーは MCP クライアントの設定にプレーンテキストで保存されるため、パスワードと同様に取り扱ってください。

データを変更できる操作

Yandex Wordstat 内のデータを変更することはできません。5 つのツールはすべて、raw_request を含めて読み取り専用です。技術的には API は POST を使用しますが、Wordstat には書き込み用のエンドポイントがありません。さらにサーバーは、任意のリクエストが別のホストに送信されないように制限しています。

データ、制限、バックグラウンドでの動作

• 集計データ。 サーバーが取得するのは検索需要の統計情報であり、特定の広告アカウントのデータではありません。
• 地域ディレクトリのキャッシュ。 長時間稼働するプロセスでは、地域ツリーを一度読み込み、その後のリクエストで再利用します。
• 一時的なエラー時の再試行。 1 回のリクエストのタイムアウトは 60 秒です。サーバーは 429、5xx、ネットワークエラー、またはタイムアウトの後、最大 3 回再試行します。Retry-After を考慮し、待機時間は 30 秒を超えません。
• バックグラウンドでの監視はありません。 サーバーは AI アプリケーションから呼び出されたときに動作します。アプリケーションがスケジュールされたタスクに対応している場合は、選択した語句の定期レポートを設定できます。
• 匿名テレメトリー。 デフォルトでは、サーバーはランダムなインストール ID、イベント名またはツール名、サーバー、Node.js、OS、AI クライアントのバージョンを送信します。API キー、ツールの引数、メッセージ、需要データ、環境変数の値は含まれません。Ask Ads の MCP サーバーで無効にするには、ASKADS_TELEMETRY=0 を設定します。

技術ドキュメント

• MCP 機能一覧 — 各ツールのユーザータスク別のページです。
• すべてのツールとパラメーター
• 開発ドキュメント
• 公開ドキュメント
• Yandex Cloud Search API のドキュメント

サポート

問題を見つけた場合や、必要なシナリオがない場合は、issue を作成するか、Telegram でご連絡ください。