yandex-webmaster-mcp

Yandex Webmaster MCP

Claude、Cursor、または任意の MCP クライアントから、Yandex Webmaster のデータを自然な言葉で確認できます。

設計上、読み取り専用（URL の再クロールを除く）で、シークレットは保存されません。組み込みのパブリック OAuth クライアントを使い、PKCE 経由でサインインできます。アプリの登録もクライアントシークレットも不要です。

開発初期段階（v0.1）です。 利用できるツールは今後も増える予定です。

Yandex Webmaster を、エンドポイントごとに薄いラッパーを用意するのではなく、柔軟で説明の充実した少数のツールとして公開する Model Context Protocol サーバーです。yandex-metrica-mcp と連携します。両方を実行すると、エージェントは Webmaster の検索クエリと、Metrica のサイト内行動やコンバージョンを、1 回の会話で相互に参照できます。

クイックスタート

1. MCP クライアントにサーバーを追加します（Claude Desktop、Cursor、…）：

{
    "mcpServers": {
        "yandex-webmaster": {
            "command": "npx",
            "args": ["-y", "@boxlab/yandex-webmaster-mcp"]
        }
    }
}

2. サインインします — 対話形式で行い、シークレットは不要です：

npx @boxlab/yandex-webmaster-mcp auth

ブラウザーでアクセスを許可し、Yandex に表示されたコードを貼り付けます。トークンは ~/.config/yandex-webmaster-mcp/token.json にキャッシュされます（モード 0600）。

3. エージェントに質問します — 例：「Webmaster のホストを一覧表示して、example.com の SQI を表示して。」

Claude Code プラグインとしてインストールする場合

/plugin marketplace add BoxLab-Ltd/yandex-webmaster-mcp
/plugin install yandex-webmaster-mcp@boxlab

このサーバーの特長

既存のコミュニティ製サーバーは、API エンドポイントごとにツールを用意し、生の JSON をモデルのコンテキストに出力する薄いラッパーであることが多いです。このサーバーは、適切に設計されたものを目指しています。より少なく、より賢いツール、簡潔で構造化された出力、そしてエージェントが Webmaster のデータを安全に確認できるよう、デフォルトで読み取り専用にしています。

ツール（v0.1）

• get_hosts — トークンから利用できるサイトを、host_id、URL、確認状態とともに一覧表示します。オプションでホストの概要（SQI、インデックス登録済み／除外ページ、サイトの問題）も取得できます。読み取り専用です。最初に呼び出してください。
• search_queries — Yandex Search の検索クエリ分析情報（表示回数、クリック数、平均表示順位／クリック順位）を取得します。report="top" は最も多くのトラフィックをもたらすクエリを順位付けし、report="trend" は時系列データ（クエリごと、またはサイト全体）を返します。デバイスと日付範囲で絞り込めます。読み取り専用です。
• get_indexing — Yandex によるホストのクロールとインデックス登録の状況を取得します。report="history" は HTTP ステータスクラスごとのクロール済みページ数を時系列で返します。report="crawled" はコード付きのクロール済み URL の例を一覧表示し、report="in_search" は現在検索結果に含まれているページの例を一覧表示します。読み取り専用です。
• get_diagnostics — サイトで検出された問題（DNS、応答の遅延、robots.txt、4xx など）を、深刻度とともに取得します。対応中の問題を先に表示します。読み取り専用です。
• list_sitemaps — Yandex が認識している Sitemap ファイルを、URL 数、エラー数、検出場所とともに一覧表示します。読み取り専用です。
• get_external_links — 外部からのリンク（バックリンク）を取得します。report="samples" はリンクの例とリンク元／リンク先を返し、report="history" は件数の推移を返します。読み取り専用です。
• recrawl_status — 1 日あたりの残りの再クロール枠と、最近の再クロールタスクおよびその状態を取得します。特定のタスクを確認するには taskId を渡します。読み取り専用です。
• recrawl_submit — 特定の URL を早めに再クロールするよう Yandex に依頼します。唯一の書き込みツールです。1 日あたりの枠を 1 つ消費し、タスク ID を返します。

予定： Sitemap、オリジナルテキスト、フィード向けの書き込みツール。後日、オプトイン形式でリリースする予定です。

要件

• Node.js >= 18
• Yandex Webmaster に少なくとも 1 つのサイトを追加済みの Yandex アカウント

認証

優先度順に、次の3つの方法があります。

1. 対話型ログイン（推奨） — npx @boxlab/yandex-webmaster-mcp auth。 PKCE を使用した組み込みの公開 OAuth クライアントを使います。トークンの有効期間は約6か月です。
2. 静的トークン — YANDEX_WEBMASTER_TOKEN を設定します（CI などで使用）。webmaster:hostinfo スコープを持つアプリの OAuth トークンを指定します。
3. 独自の OAuth アプリ — YANDEX_OAUTH_CLIENT_ID を設定します（トークンの自動更新を有効にするには、YANDEX_OAUTH_CLIENT_SECRET も設定します）。アプリには webmaster:hostinfo と webmaster:verify のスコープが必要です。

すべての設定については、.env.example を参照してください。

開発

Bun を優先します。

bun install
bun run dev          # watch mode
bun run typecheck
bun run lint
bun test
bun run build        # emits dist/ (Node-compatible)
bun run try          # smoke against the real API after `bun run auth`

公開パッケージは Node で動作し、ローカル開発では Bun を使用します。

ライセンス

MIT