Yandex Webmaster MCP

yandex-webmaster-mcp

Yandex Webmaster API v4 用の MCP サーバーです。サイトの健全性、インデックス登録状況、検索クエリ、被リンク、サイトマップなどを監視できます。

インストール

このパッケージは @stufently/yandex-webmaster-mcp として公開されています。スコープなしの名前 yandex-webmaster-mcp は無関係の公開者に属しています（ルートの README の注記を参照）。 まだスコープには何も公開されていないため、ソースから実行してください。

git clone https://github.com/stufently/yandex-mcp.git
cd yandex-mcp && bun install
node packages/yandex-webmaster-mcp/src/index.mjs

設定

MCP クライアントの設定に追加してください。

{
  "mcpServers": {
    "yandex-webmaster": {
      "command": "node",
      "args": ["/path/to/yandex-mcp/packages/yandex-webmaster-mcp/src/index.mjs"],
      "env": {
        "YANDEX_WEBMASTER_TOKEN": "your-oauth-token"
      }
    }
  }
}

環境変数

変数	必須	説明
YANDEX_WEBMASTER_TOKEN	はい	Webmaster API 用の OAuth トークン
YANDEX_CLIENT_ID	認証フローで必要	Yandex OAuth アプリのクライアント ID
YANDEX_CLIENT_SECRET	認証フローで必要	Yandex OAuth アプリのクライアントシークレット

認証

OAuth トークンを対話形式で取得するには、次を実行してください。

node packages/yandex-webmaster-mcp/src/index.mjs auth

Yandex OAuth 認証用にブラウザーが開き、トークンが返されます。トークンを YANDEX_WEBMASTER_TOKEN として設定してください。

注：Webmaster API では Authorization: OAuth {token} を使用します（Bearer ではありません）。

エージェント向けプレイブック

このファイルと同じ場所にある SKILL.md は、エージェント向けのタスクレベルのガイドです。新規サイトの手順、定期監査の順序、再クロールのルール、3 種類の時系列データの読み方、そして重要な点として、API v4 に存在しない機能（IndexNow、robots.txt、サイトの地域、ファビコン、モバイルステータス、Metrika のバインド）を説明し、機能を捏造しないようにしています。

ツールリファレンス（33 個のツール）

コア（3）

ツール	説明	パラメーター
get-user	現在の Webmaster ユーザー情報と user_id を取得します	--
list-hosts	すべてのホスト（サイト）を、他のすべてのツールで必要となる識別子である host_id とともに一覧表示します	--
get-host	特定のホストの詳細を取得します	host_id

統計（2）

ツール	説明	パラメーター
get-summary	サイトの概要（SQI、ページ数、問題）を取得します	host_id
get-sqi-history	SQI（サイト品質指標）の履歴を取得します	host_id、date_from?、date_to?

診断（1）

ツール	説明	パラメーター
get-diagnostics	サイトの診断と問題を取得します	host_id

検索クエリ（2）

ツール	説明	パラメーター
get-popular-queries	サイトの人気検索クエリを取得します	host_id、order_by（TOTAL_SHOWS/TOTAL_CLICKS）、device_type?、date_from?、date_to?、limit?（1-500、デフォルト：100）、offset?
get-query-history	検索クエリの合計数の履歴を取得します	host_id、device_type?、date_from?、date_to?

インデックス登録（4）

ツール	説明	パラメーター
get-indexing-history	時系列でのインデックス登録履歴を取得します	host_id、date_from?、date_to?
get-indexing-samples	インデックス登録済み URL のサンプルを取得します	host_id、limit?（1-100）、offset?
get-insearch-history	検索結果に表示された履歴を取得します	host_id、date_from?、date_to?
get-insearch-samples	検索結果に表示された URL のサンプルを取得します	host_id、limit?（1-100）、offset?

検索イベント（3）

ツール	説明	パラメーター
get-search-events-history	検索 URL イベントの履歴を取得します	host_id、date_from?、date_to?
get-search-events-samples	検索イベントのサンプル URL を取得します。URL ごとの除外理由も含みます（excluded_url_status）。取得したページの exclusion_reasons 集計と、URL → 理由の一覧である excluded_pages が含まれます	host_id、event_type?（APPEARED_IN_SEARCH/REMOVED_FROM_SEARCH — クライアント側のフィルターです。API にはありません）、limit?（1～100、デフォルト：10）、offset?
get-excluded-pages	期間内に検索結果から除外されたページと、それぞれの excluded_url_status を返します。 REMOVED_FROM_SEARCH イベントから作成され、URL ごとに重複を除去します（最新のイベントを採用するため、検索結果に戻ったページは代わりに returned_to_search に報告されます）。除外ページが limit 件集まるまで、イベントが混在するストリームをページごとに取得し、処理を続けられるよう next_offset（次に読み込むイベント）／exhausted を報告します。照合用に summary_excluded_pages_count も返します	host_id、limit?（除外ページ数、1～100、デフォルト：20）、offset?、max_requests?（ページ取得の最大回数、1～50。再試行は含まず、デフォルト：10）、returned_urls?（処理を続ける際、前回の returned_to_search を渡します）

API v4 には専用の「除外ページ」リソースはありません。get-summary には集計値の excluded_pages_count のみが含まれ、特定の URL が除外された理由は /search-urls/events/samples の REMOVED_FROM_SEARCH レコードに記録されています。API に サーバー側のイベントフィルターはないため、count は引き続き両方のイベントタイプを数え、 limit／offset はイベントが混在するストリームをページ分割します。 get-search-events-samples はそのようなページの内容を返し、 get-excluded-pages はページを順に取得するため、その limit が数えるのはイベントではなく 除外ページです。ステータスコード以外の URL ごとの詳細として、HTTP_ERROR の場合は bad_http_status、リダイレクト先、正規 URL、または重複 URL の場合は target_url が返されます。

これはインデックスのスナップショットではなく、時間上のイベントです。 同じ URL が REMOVED_FROM_SEARCH の後に APPEARED_IN_SEARCH として現れることがあります。検索結果から 消えた後に戻ってきたため、現在は検索結果に含まれています。そのため get-excluded-pages は URL ごとに 重複を除去し、最新のイベントを保持します。最新のイベントが表示である URL は pages ではなく returned_to_search に含まれます。特に、次の点に注意してください。

• スキャン対象期間より前の除外は、どれだけ最近のものであっても検出されません。
• 重複除去は1 回の呼び出しの範囲で行われます。next_offset から続けると状態が空のまま始まるため、 前の期間に検索結果へ戻ったページが再び除外として報告されます。処理を正しく続けるには、前回の returned_to_search を returned_urls に渡してください。
• get-summary の excluded_pages_count と pages の件数は、異なる種類の数値であり、一致するとは 想定されていません。このツールは集計値を summary_excluded_pages_count として返し、本文でもその旨を 示すため、利用者が自分で 25 倍もの差に気づく必要はありません。

URL ごとのステータスフィールド名は、ツールの説明、get-search-events-samples の excluded_pages、get-excluded-pages の pages のすべてで excluded_url_status に統一されています。 これは Yandex のリファレンス（ApiExcludedUrlStatus）にある名前なので、ドキュメント内で検索できます。

リンク（4）

ツール	説明	パラメーター
get-external-links	サイトにリンクしている外部リンクを取得します	host_id、limit?（1-100）、offset?
get-external-links-history	外部リンク数の履歴を取得します	host_id、date_from?、date_to?
get-broken-internal-links	破損した内部リンクを一覧表示します。リンク先 URL、リンク元ページ、Yandex が最後にリンクを確認した日時を含みます。各レコードには days_since_last_check、never_rechecked、stale（最後の確認から90日超）も含まれます	host_id、limit?（1-100）、offset?
get-broken-internal-links-history	破損した内部リンク数の履歴を取得します	host_id、date_from?、date_to?

破損リンクのレコードは、Yandex がそのリンクを最後に確認した時点のスナップショットであり、その時点から数か月経っている場合があります。source_last_access_date が discovery_date と同じ場合、問題が見つかってから再確認されていないため、リンクはかなり前に修正されている可能性があります。そのため各レコードには days_since_last_check、never_rechecked、stale（最後の確認から90日超。never_rechecked だけでは該当しません）が含まれ、テキストブロックでは警告が一覧の上に表示されます。これらのサイトで破損と報告された258件のリンクをライブチェックしたところ（2026-09-02）、実際の404は10件で、約80％は301リダイレクトでした。APIは誤った情報を返していたわけではありません。以前の一行だけの出力では、件数が障害のように見えていただけです。

⚠️ Yandex のリファレンスでは、source_last_access_date の名前と説明が一致していません。名前には source とありますが、説明には「ロボットがリンクのリンク先ページを最後に訪問した日付」とあります。ここでは表現を「最後に確認した日時」と中立的にしています。これは、レコードの古さについての結論はどちらの解釈でも変わりませんが、特定のページについての結論は変わるためです。

サイトマップ（4）

ツール	説明	パラメーター
get-sitemaps	ホストのすべてのサイトマップを一覧表示します	host_id、limit?（1-100）
get-sitemap	特定のサイトマップの詳細を取得します	host_id、sitemap_id
get-user-sitemaps	ユーザーが追加したサイトマップを一覧表示します	host_id、limit?（1-100）
add-sitemap	書き込み。 ユーザーのサイトマップファイルを追加し、sitemap_id を返します。追加専用です。ファイルは Webmaster パネルから削除できます	host_id、url

add-sitemap を使うには、ホストの認証が必要です（認証されていない場合は 404 HOST_NOT_VERIFIED）。すでに存在するファイルを追加すると 409 SITEMAP_ALREADY_ADDED が返されます。ここではほかの2xx以外の応答と同様にエラーとして通知され、ペイロードには既存の sitemap_id が含まれます。再試行せず、「すでに存在する」と解釈してください。サイトマップの削除（DELETE /user-added-sitemaps/{id}）は API に存在しますが、意図的にここではラップしていません。

重要な URL（2）

ツール	説明	パラメーター
get-important-urls	サイトの重要な URL を取得します	host_id、limit?（1-100）、offset?
get-important-url-history	特定の重要な URL の履歴を取得します	host_id、url、date_from?、date_to?

再クロール（4）

ツール	説明	パラメーター
get-recrawl-quota	再クロールの割り当て（1日の上限と残数）を取得します	host_id
add-recrawl-url	書き込み。 URL を再クロールのキューに追加します。1日の割り当てを消費します	host_id、url
get-recrawl-queue	送信済みの再クロールタスクとその状態を一覧表示します	host_id、limit?（デフォルト：10）、offset?
get-recrawl-task	1件の再クロールタスクの状態を取得します	host_id、task_id

ホスト管理（4）

以下は、Webmaster アカウントを変更する操作であり、データを読み取るだけではありません。

ツール	説明	パラメーター
add-host	書き込み。 Webmaster にサイトを追加します（その後、確認が必要です）。追加操作です。delete-host で取り消せます	host_url（プロトコルを含む）
verify-host	確認状態と、利用可能な確認方法を取得します	host_id
start-verification	書き込み。 所有権の確認を開始します（POST …/verification、本文なし）。verification_uin がサイトにすでに存在している必要があります。確認は非同期で行われます。verify-host をポーリングしてください。追加操作です	host_id、verification_type（HTML_FILE / META_TAG / DNS）
delete-host	書き込み。 Webmaster からサイトを削除します。元に戻せません。詳しくはホストの削除をご覧ください。confirm: true が必要です	host_id、confirm

ホストの削除

delete-host は、ここにあるツールのうち唯一、元に戻せない操作を行うツールであり、呼び出しに confirm: true が含まれていない限り実行を拒否します。

{ "host_id": "https:example.com:443", "confirm": true }

これを指定せずに呼び出すと、ツールはエラー結果を返し、Webmaster API には何も送信しません。

Refused: `delete-host` requires explicit confirmation.

Removing host https:example.com:443 from Yandex Webmaster is irreversible — the site's
verification, its accumulated indexing and search-query history, and its sitemap and
important-URL settings go with it. Adding the same site back creates a fresh host that must be
verified again and starts with no history.

Nothing was sent to the Webmaster API — no host was touched.

To go ahead, call `delete-host` again with host_id https:example.com:443 and `confirm: true`.
To check which site this host ID stands for first, call `get-host-info` or `list-hosts`.

confirm は意図的に JSON スキーマで任意項目にしています。確認がない場合、モデルが対処できないスキーマ検証エラーではなく、説明を返す必要があるためです。文字どおりの true だけが有効です。プロトコルを推測した値は何かを削除する決定ではないため、"true"、1、"yes" は拒否されます。また、このツールは MCP アノテーションで destructiveHint: true としてマークされているため、ツールのリスクを表示するクライアントは、呼び出し前にそれを示すことができます。

他の 3 つの書き込み操作には、意図的に保護を設けていません。add-host は追加操作であり、delete-host で取り消せます。add-recrawl-url は、日ごとに補充される上限枠に対して URL の再クロールをキューに登録するだけです。また、add-sitemap は削除可能なファイルを追加するだけで、履歴も残しません。すべての書き込み操作で確認を求めると、呼び出し元が反射的に confirm: true を渡すようになり、肝心の呼び出しで確認が機能しなくなります。

共通パラメーター

• host_id -- ホスト識別子（URL エンコード済み。例：https:example.com:443）。list-hosts から取得します。
• date_from、date_to -- YYYY-MM-DD 形式の日付です。厳密に検証されます（無通知の日付オーバーフローは発生しません）。
• limit、offset -- ページネーション制御です。
• device_type -- 次のいずれかです：ALL、DESKTOP、MOBILE、TABLET、MOBILE_AND_TABLET。

キャッシュ

user_id は最初の API 呼び出し時に一度取得され、セッション中はキャッシュされます。401/403 エラーが発生すると、自動的に無効化されます。

ライセンス

MIT