SEO Tools: Google Analytics 4

seo-tools-mcp

ロシア語 | 英語

SEO向けの汎用stdio MCP サーバーを8つ提供します。SERP、Wordstat、Google Search Console、Google Analytics 4、Яндекс.Вебмастер、Яндекс.Метрика、セルフホスト可能な A-Parser に、Claude Code（およびあらゆる MCP クライアント）から直接アクセスできます。すべてのツールは読み取り専用で、アカウントに何かを公開したり変更したりすることはありません。出力は厳密な JSON です。機械可読性のため、readOnlyHint アノテーションで宣言しています。XMLStock／XMLRiver へのリクエストや A-Parser のプロキシトラフィックなど、呼び出すたびに有料リソースを消費する20個のツールには、意図的にこのアノテーションを付けていません。付けると、クライアントがこれらを無害だと判断し、大規模な処理を実行する前に確認を求めなくなるためです。特定のサイトには紐付いていません。デフォルト（GSC プロパティ、GA4 プロパティ、ウェブマスターホスト、メトリカカウンター）はその場で設定できます。

🛰 これらのサーバーは、検索上位を目指すためのインフラである**PBN Workers**の本番環境で使用しています。セマンティクス、PBN、サテライト、SEO の自動化に対応しています。安定したオーガニックトラフィックが必要な方は、ぜひお越しください。

サーバー	利用可能なツール	認証
xmlstock	xmlstock_serp, xmlstock_images, xmlstock_news, xmlstock_video, xmlstock_wordstat, xmlstock_wordstat_dynamics, xmlstock_wordstat_regions, xmlstock_wordstat_regions_tree, xmlstock_balance	API キー
xmlriver	xmlriver_serp, xmlriver_images, xmlriver_news, xmlriver_maps, xmlriver_check_index, xmlriver_suggest, xmlriver_related_questions, xmlriver_balance	API キー
wordstat	wordstat_frequency, wordstat_dynamics, wordstat_regions, wordstat_regions_tree	Yandex Cloud の Api-Key
gsc	gsc_query, gsc_inspect_url, gsc_list_sites, gsc_get_site, gsc_list_sitemaps, gsc_get_sitemap	OAuth（アカウント内のすべてのプロパティ）／サービスアカウント
ga4	ga4_list_properties, ga4_property_details, ga4_metadata, ga4_check_compatibility, ga4_report, ga4_bytime, ga4_traffic_sources, ga4_geo, ga4_devices, ga4_top_pages, ga4_events, ga4_funnel, ga4_annotations, ga4_realtime	OAuth（アカウント内のすべてのプロパティ）／サービスアカウント
ywm	ywm_hosts, ywm_summary, ywm_search_queries, ywm_queries_history, ywm_recommended_queries, ywm_popular, ywm_indexing_history, ywm_sqi_history, ywm_external_links, ywm_broken_links, ywm_diagnostics, ywm_important_urls, ywm_sitemaps	OAuth（自動更新）
metrika	metrika_report, metrika_bytime, metrika_counters, metrika_goals, metrika_traffic_sources, metrika_geo, metrika_devices, metrika_landing_behavior, metrika_search_phrases, metrika_top_landings	OAuth（自動更新）
aparser	aparser_ping, aparser_status, aparser_proxies, aparser_parsers, aparser_parser_fields, aparser_get_preset, aparser_serp_google, aparser_serp_yandex, aparser_suggest, aparser_request, aparser_bulk_request	セルフホスト可能な A-Parser（URL + API パスワード）

公開先：npm（8パッケージ）、公式 MCP Registry、GitHub MCP Registry（8つすべてのサーバー）、Claude Code のプラグインマーケットプレイス（以下を参照）、リリース内の.mcpbバンドル。

各サーバーには、認証用ツール<server>_auth_statusおよび<server>_set_credentialsもあります（対話型認証を参照）。

サービス別ツール

xmlstock — Google／Yandex SERP

• xmlstock_serp — Google／Yandexのウェブ検索結果（オーガニック検索＋ハイライト＋SERP機能）：地域、デバイス、セーフサーチ、並べ替え（Yandex）、期間、広告ブロック。3つ目のエンジン yandex_xml は公式のYandex XMLです（1回のリクエストで最大100件のgroupby、あらゆるデバイスでhlword、found/found-docsの統計。料金は1000件あたり24 ₽から）
• xmlstock_images — Google画像検索（ページURL＋画像URL＋タイトル）
• xmlstock_news — Googleニュース（タイトル、ソース、日付、スニペット）
• xmlstock_video — Google動画（URL、タイトル、プレビュー、ホスト、チャンネル、再生時間）
• xmlstock_wordstat — Yandex Wordstat：頻度付きの上位クエリ＋類似クエリ（地域指定可）、Wordstat演算子
• xmlstock_wordstat_dynamics — 時間ごとの検索頻度の推移（日／週／月）
• xmlstock_wordstat_regions — 地域別の需要（count、share、affinity index＋地域名）
• xmlstock_wordstat_regions_tree — Wordstatの地域ツリー（id＋名前＋パス）
• xmlstock_balance — アカウント残高／キーの確認（無料）

XMLStock経由のWordstatはSERPと同じ XMLSTOCK_* キーを使用します。Yandex Cloudは不要です（専用サーバー wordstat とは異なります）。

xmlriver — Google／Yandex SERP＋インデックス登録の確認

• xmlriver_serp — Google／Yandexのオーガニック検索結果（ページネーションで指定した深さまで取得：10件ごとに有料リクエスト1回）、AI Overviewの有無を示すフラグ。オプションの includeAIOverview はAI Overviewの全文＋引用リンクを返します（有料の ai=1、Googleのみ）。includeAdditional は <addresults> に含まれるGoogleの追加SERPブロック（knowledge_graph、localresultsplace、rsなど）を返します。内容はXMLRiverアカウントの有料オプションによって異なり、取得できなかったブロックは additional.unavailable に表示されます。Googleの地域ターゲティングは location（都市 → loc、「Moscow」／「1011969」）と country（ISO／数値ID。都市から自動で特定）で指定します。device はdesktop／mobile／tablet、os（ios／android）は device=mobile の場合のみ送信されます
• xmlriver_images — Google画像検索（ページ＋画像URL＋タイトル＋ソース＋サイズ）。地域は location／country で指定します
• xmlriver_news — Googleニュース（タイトル、ソース、日付、スニペット）、期間フィルター。地域は location／country で指定します
• xmlriver_maps — Google Mapsでの店舗検索（setab=maps、必須の zoom は1～15、coords は「緯度,経度」、count は5～50）：名称、評価、住所、電話番号、サービス、座標、place_id、レビュー数。重要：仕様書に基づく形式で、実環境では未確認です（テストアカウントではエンドポイントが一貫してコード500を返します。アカウントの有料オプションが必要な可能性があります）
• xmlriver_check_index — Google／YandexでのURLのインデックス登録を確認（inindex）
• xmlriver_suggest — Google検索候補（1回の呼び出しで最大50フレーズ。フレーズごとに課金）。候補の地域は location／country で指定します
• xmlriver_related_questions — Googleの「関連する質問」／People Also Askブロック（質問は常に表示されます。回答は、アカウントで有料オプション「Related Questions с ответами」が有効な場合のみ表示されます）
• xmlriver_balance — アカウント残高／キーの確認（無料）

wordstat — Yandexの検索頻度

• wordstat_frequency — 広範一致と完全一致の検索頻度、絞り込みクエリ（related）、関連語
• wordstat_dynamics — 時間ごとの検索頻度（日／週／月）
• wordstat_regions — アフィニティインデックスと地域名を含む地域別分布
• wordstat_regions_tree — Wordstatの完全な地域ツリー（id＋名前）

gsc — Google Search Console

• gsc_query — 検索アナリティクス（クリック数／表示回数／CTR／掲載順位）、自動ページネーション、dataState の final／all、任意のディメンションフィルター（filters、AND セマンティクス）、aggregationType（auto／byProperty／byPage）
• gsc_inspect_url — URL 検査：インデックス登録状況、カバレッジ、canonical、最終クロール、モバイルユーザビリティ、リッチリザルト
• gsc_list_sites — 認証情報で利用可能なプロパティ
• gsc_get_site — プロパティへのアクセスレベル
• gsc_list_sitemaps — ステータス付きの送信済み sitemap
• gsc_get_sitemap — 1 つの sitemap の詳細

Search Analytics の日付は太平洋時間（モスクワ時間ではありません）で、履歴は約 16 か月分です。確定データの反映には約 2～3 日かかります（最新データには dataState=all を使用します）。応答の ctr は 0～1 の比率です。

ga4 — Google Analytics 4

• ga4_list_properties — 認証情報で利用可能な GA4 プロパティ（ここから propertyId を取得します。これは Measurement ID G-XXXXXXX ではありません）
• ga4_metadata — カスタムディメンション／カスタム指標（customEvent:…）を含む、このプロパティで利用可能なディメンションと指標。部分文字列で検索でき、blockedReasons（その指標を使ったレポートはゼロを返します）と type（metricFilters で使用する整数／小数）も確認できます
• ga4_check_compatibility — このプロパティでディメンションと指標の組み合わせが互換かどうかを、負荷の高いレポートを実行せずに確認します。互換性がない場合は、削除すべきフィールドを示します
• ga4_report — 任意のレポート：任意のディメンションと指標の組み合わせ、ディメンションフィルター、並べ替え（Data API の完全な runReport）
• ga4_bytime — 時間単位（日／時間／週／月）の指標推移
• ga4_traffic_sources — トラフィックソース：チャネルグループ、source/medium、キャンペーン。organicOnly はオーガニックのみ
• ga4_geo — 国／地域／市区町村
• ga4_devices — デバイスの種類／OS／ブラウザー
• ga4_top_pages — pagePath、ランディングページ、またはページタイトル別の上位ページ。organicOnly と pathContains フィルターを使用できます
• ga4_events — eventName 別のイベント。keyEventsOnly は重要なイベント（旧コンバージョン）のみ
• ga4_realtime — リアルタイムレポート（直近 30 分間）
• ga4_funnel — ファネル（runFunnelReport）：各ステップに到達した数と離脱箇所を示します。ステップはイベントおよび／またはディメンション条件で指定し、ディメンションで分類できます。ステップ内では Exploration API の仕様が適用されます（pagePath は利用できません）。割り当て枠は別で、通常のレポートよりクエリのコストが高くなります
• ga4_annotations — プロパティのアノテーション：日付に付けられた注記。GA4 が自動作成したもの（systemGenerated）も含み、推移で説明のつかない急変が起きた場合によく原因となります
• ga4_property_details — プロパティの詳細：レポートのタイムゾーン、通貨、サービスレベル（STANDARD／360）、および Measurement ID G-XXXXXXX 付きのデータストリーム

すべてのレポートツールには includeQuota があり、クエリで Data API の「トークン」をいくつ消費したか、また 1 時間／1 日あたりの残量を確認できます。

単位と日付：GA4 が返す bounceRate／engagementRate は 0～1 の比率（パーセントではありません）です。日付はプロパティのタイムゾーンで計算されます。YYYY-MM-DD と GA4 のキーワード（today、yesterday、28daysAgo）を受け付け、実際のタイムゾーンは応答に含まれます。応答には totalRows／truncated が含まれ、thresholded: true は GA4 のプライバシーしきい値によりデータの一部が非表示であることを示します。

ywm — Яндекс.Вебмастер

• ywm_hosts — ユーザー ID と確認済みサイト
• ywm_summary — ИКС、検索結果に含まれるページ数、除外数、重要度別のサイトの問題
• ywm_search_queries — URL 別のクエリ分析（デフォルトで約 2 週間分。dateFrom/dateTo で変更できます）
• ywm_queries_history — 時間経過に伴う合計表示回数／クリック数／掲載順位
• ywm_recommended_queries — 推奨クエリの概算値（検索需要＋クリック数の不足分）
• ywm_popular — ホストの人気クエリ
• ywm_indexing_history — 時間経過に伴う検索結果内のページ数
• ywm_sqi_history — 時間経過に伴う ИКС
• ywm_external_links — 外部リンクのサンプルと合計数
• ywm_broken_links — 内部／外部のリンク切れ
• ywm_diagnostics — サイトの問題
• ywm_important_urls — インデックス登録／検索状況付きの追跡対象 URL
• ywm_sitemaps — ステータス付きの sitemap

metrika — Яндекс.Метрика

• metrika_report — произвольный отчёт: любые dimensions × metrics, фильтры, сортировка (полный Stat API)
• metrika_bytime — метрики по времени (день/неделя/месяц/час)
• metrika_traffic_sources — визиты/пользователи/отказы по источникам трафика
• metrika_geo — визиты по стране/региону/городу
• metrika_devices — визиты по устройству/ОС/браузеру
• metrika_goals — список целей (конверсий)
• metrika_counters — доступные счётчики
• metrika_landing_behavior — поведение на посадочных + достижения целей
• metrika_search_phrases — поисковые фразы (органика)
• metrika_top_landings — топ органических посадочных

aparser — мост к self-hosted A-Parser

• aparser_ping — проверка связи с инстансом и пароля API
• aparser_status — вердикт готовности: версия, установленные парсеры, очередь, живые прокси
• aparser_proxies — живые прокси инстанса (можно по пачкам proxy checkers; креды прокси не выводятся)
• aparser_parsers — парсеры, установленные на инстансе
• aparser_parser_fields — поля результата, которые умеет вернуть парсер (flat + arrays)
• aparser_get_preset — опции config-пресета парсера (чувствительные значения маскируются)
• aparser_serp_google — органика Google (парсер SE::Google); прокси по умолчанию + preflight живых прокси
• aparser_serp_yandex — органика Яндекса (SE::Yandex); регион через lr
• aparser_suggest — поисковые подсказки Google/Яндекса
• aparser_request — универсальный синхронный запрос к любому парсеру (oneRequest)
• aparser_bulk_request — пакетный запрос: один парсер, много запросов в N потоков (bulkRequest)

Нужен свой запущенный инстанс A-Parser (лицензия + сервер): мост им управляет, но не хостит и не проксирует его. Прокси и прокси-чекеры (пачки) настраиваются один раз в GUI A-Parser — мост их читает, проверяет (preflight) и выбирает (checkers), но не создаёт. v1 синхронный и read-only: очередь задач и большие асинхронные выгрузки не подключены.

Быстрый старт

Вариант 1 — в один клик для Claude Desktop (.mcpb)

Самый простой способ, ничего ставить руками не нужно: скачай нужный .mcpb со страницы релиза и открой двойным кликом — Claude Desktop поставит сервер сам и спросит ключи в диалоге установки.

• Серверы с API-ключом (xmlstock, xmlriver, wordstat, aparser) — ключи вводятся прямо в установщике.
• Серверы на OAuth (gsc, ga4, ywm, metrika) ничего не спрашивают: авторизация проходит в чате (<server>_oauth_start → <server>_oauth_finish).

Бандлы самодостаточны (~0.2 МБ, зависимости внутри), Node.js 20+ нужен только для варианта с npx. Собрать самому: pnpm build:mcpb.

Вариант 2 — плагин для Claude Code (маркетплейс)

Аналог .mcpb, но для Claude Code: сервер, ключи и подсказки ставятся одной командой, ключи спрашиваются диалогом, секреты уходят в системное хранилище, а не в открытый файл.

claude plugin marketplace add antohins/seo-tools-mcp

Дальше — только те источники, которые нужны; каждый плагин тянет ровно один сервер:

claude plugin install xmlstock@seo-tools-mcp
claude plugin install gsc@seo-tools-mcp
claude plugin install ga4@seo-tools-mcp

Доступны xmlstock, xmlriver, wordstat, gsc, ga4, ywm, metrika, aparser — и seo-tools, который ставит все восемь сразу. Бандл удобен, но это ~100 инструментов в каждой сессии: если работаешь только с Вебмастером и Метрикой, ставь два плагина, а не бандл.

Ключи можно ввести сразу (--config KEY=VALUE) или потом через /plugin configure <плагин>@seo-tools-mcp:

claude plugin install xmlstock@seo-tools-mcp --config XMLSTOCK_USER=12345 --config XMLSTOCK_KEY=...

Поля, помеченные как секретные (API-ключи, OAuth-секреты), Claude Code кладёт в системное хранилище; в settings.json они не попадают. Плагины на OAuth (gsc, ga4, ywm, metrika) при установке спрашивают только client_id/secret — сам вход проходит в чате через <сервер>_oauth_start → <сервер>_oauth_finish.

Вместе с сервером плагин приносит навыки — процедурные инструкции по своему источнику: как не сжечь баланс на снятии позиций, почему freq_broad завышает трафик в разы, отчего GA4 молча отдаёт нули, чем усреднённая позиция GSC отличается от снятой из выдачи. В контексте они всегда занимают ~110 токенов на навык и разворачиваются, только когда действительно нужны.

Вариант 3 — через npx (без клонирования)

Каждый сервер — самодостаточный npm-пакет seo-tools-mcp-<сервер>; ставится одной командой:

claude mcp add xmlstock --scope user -- npx -y seo-tools-mcp-xmlstock
claude mcp add xmlriver --scope user -- npx -y seo-tools-mcp-xmlriver
claude mcp add wordstat --scope user -- npx -y seo-tools-mcp-wordstat
claude mcp add gsc      --scope user -- npx -y seo-tools-mcp-gsc
claude mcp add ga4      --scope user -- npx -y seo-tools-mcp-ga4
claude mcp add ywm      --scope user -- npx -y seo-tools-mcp-ywm
claude mcp add metrika  --scope user -- npx -y seo-tools-mcp-metrika
claude mcp add aparser  --scope user -- npx -y seo-tools-mcp-aparser

Нужен только один сервер?

Серверы не связаны между собой: возьмите один пакет и игнорируйте остальные. Каждый самодостаточен — общий код @seo-tools/shared вшит в сборку, так что лишних зависимостей и «хвоста» монорепы не тянется. Достаточно установить нужный пакет с npm — там уже всё из коробки (npx -y скачает и запустит его сам):

Пакет (npm)	Сервер
seo-tools-mcp-xmlstock	SERP Google/Яндекс + Wordstat
seo-tools-mcp-xmlriver	SERP Google/Яндекс + проверка индексации
seo-tools-mcp-wordstat	частотности Яндекса (Yandex Cloud)
seo-tools-mcp-gsc	Google Search Console
seo-tools-mcp-ga4	Google Analytics 4
seo-tools-mcp-ywm	Яндекс.Вебмастер
seo-tools-mcp-metrika	Яндекс.Метрика
seo-tools-mcp-aparser	мост к self-hosted A-Parser

# добавить один сервер в Claude Code
claude mcp add xmlstock --scope user -- npx -y seo-tools-mcp-xmlstock

# или запустить напрямую (ключи через env)
XMLSTOCK_USER=... XMLSTOCK_KEY=... npx -y seo-tools-mcp-xmlstock

В любом MCP-клиенте (Claude Desktop, Cursor…) — прописывается один блок в mcpServers:

{
  "mcpServers": {
    "xmlstock": {
      "command": "npx",
      "args": ["-y", "seo-tools-mcp-xmlstock"],
      "env": { "XMLSTOCK_USER": "...", "XMLSTOCK_KEY": "..." }
    }
  }
}

Прямая установка одного пакета по GitHub-ссылке (npm i github:antohins/seo-tools-mcp) не поддерживается: это pnpm-монорепа, отдельный подпакет так не ставится. Для установки из исходников — вариант Б ниже (клонировать + собрать). Готовые пакеты живут на npm.

Вариант 4 — из исходников

git clone https://github.com/antohins/seo-tools-mcp.git && cd seo-tools-mcp
pnpm install && pnpm build
ROOT=$(pwd)
for s in xmlstock xmlriver wordstat gsc ga4 ywm metrika aparser; do
  claude mcp add "$s" --scope user -- node "$ROOT/servers/$s/dist/index.js"
done

Дальше (любой вариант) — прямо в диалоге Claude Code: «настрой доступ к xmlstock» → агент вызовет xmlstock_auth_status, подскажет, какие ключи нужны и где их взять, примет их через xmlstock_set_credentials и сохранит. После этого спрашивайте данные обычным языком: «сними топ-10 Яндекса по запросу X», «частотность фраз …», «клики/показы из GSC за месяц». Ключи и OAuth настраиваются один раз (см. Получение доступов).

Интерактивная авторизация (в любой сессии)

У каждого сервера есть auth-инструменты — ключи можно выдавать прямо в диалоге, без правки файлов и перезапуска:

• <server>_auth_status — вызывается в начале работы: показывает, какие ключи заданы (маскированно), каких не хватает и как их получить (шаги регистрации).
• <server>_set_credentials — сохраняет переданные значения в ~/.config/seo-tools-mcp/.env (права 600) и применяет сразу.
• gsc_save_sa_json — принимает содержимое JSON-ключа сервис-аккаунта, кладёт его в конфиг-директорию и возвращает email, который нужно добавить в GSC.
• ywm_oauth_start / metrika_oauth_start → ссылка авторизации Яндекса; пользователь открывает, разрешает, копирует код → *_oauth_finish обменивает код на access+refresh токены. Дальше токен обновляется автоматически при протухании (code flow, не implicit).

Типовой сценарий новой сессии: «настрой доступ к xmlstock» → агент вызывает xmlstock_auth_status → просит недостающие ключи → xmlstock_set_credentials → работает.

⚠ Ключи, переданные через чат, проходят через контекст модели. Для максимальной гигиены можно по-прежнему вписать их в ~/.config/seo-tools-mcp/.env руками — серверы подхватят файл сами.

Мультиаккаунт

Клиентские сайты раскиданы по разным аккаунтам Google/Яндекса — поддерживаются именованные профили:

• Каждый рабочий инструмент принимает опциональный параметр account («clientX», «agency»...). Без него используется основной профиль — обратная совместимость полная.
• Ключи профиля хранятся в том же конфиге с суффиксом: GSC_REFRESH_TOKEN__clientX, YANDEX_OAUTH_TOKEN__clientX, XMLSTOCK_KEY__clientX…
• Добавление профиля: gsc_oauth_start(account="clientX") → пользователь авторизуется под другим Google-аккаунтом → gsc_oauth_finish(account="clientX"). Аналогично ywm_oauth_start/finish(account=...) для Яндекса; API-ключи — <server>_set_credentials(account="clientX", ...).
• OAuth-приложения общие: один Google-client и одно Яндекс-приложение обслуживают все профили (клиент создаётся один раз, авторизаций — сколько угодно). Per-account хранятся только токены; refresh обновляет токен своего профиля.
• Резолв строгий: account="clientX" без настроенных ключей → ошибка со списком настроенных профилей (никаких тихих фолбэков в чужой аккаунт). Дефолты (GSC_SITE_URL__clientX, YWM_HOST_ID__clientX, METRIKA_COUNTER_ID__clientX) — тоже per-account.
• <server>_auth_status показывает все профили и их ключи (маскированно).
• Альтернатива для жёсткой изоляции: отдельный env-файл через SEO_TOOLS_MCP_ENV (при заданном пути домашний конфиг НЕ читается).

Установка

cd seo-tools-mcp
pnpm install
pnpm build

Секреты

Единый env-файл: ~/.config/seo-tools-mcp/.env (права 600). Все серверы читают его при старте, а *_set_credentials/*_oauth_finish пишут в него сами — ручная правка не обязательна. Шаблон — .env.example. Переменные из окружения процесса имеют приоритет над файлом. Альтернативный путь к файлу — SEO_TOOLS_MCP_ENV (так один хост может держать несколько независимых профилей: разные claude mcp add с разным SEO_TOOLS_MCP_ENV).

Регистрация в Claude Code

ROOT=/path/to/seo-tools-mcp
claude mcp add xmlstock --scope user -- node $ROOT/servers/xmlstock/dist/index.js
claude mcp add wordstat --scope user -- node $ROOT/servers/wordstat/dist/index.js
claude mcp add gsc      --scope user -- node $ROOT/servers/gsc/dist/index.js
claude mcp add ga4      --scope user -- node $ROOT/servers/ga4/dist/index.js
claude mcp add ywm      --scope user -- node $ROOT/servers/ywm/dist/index.js
claude mcp add metrika  --scope user -- node $ROOT/servers/metrika/dist/index.js

--scope user — доступно во всех сессиях/проектах. Для шаринга на команду — --scope project (создаст .mcp.json в репозитории; секреты подставлять только через ${VAR}).

Получение доступов (по сервису)

Всё из этого раздела продублировано в ответах <server>_auth_status — агент сам подскажет шаги. Ниже — для чтения человеком.

XMLStock（優先度 1）— Google + Яндекс の SERP

1. 登録：https://xmlstock.com → アカウントページで残高をチャージします（Google XML と Яндекс Live は 1000 クエリあたり 12 ₽から）。
2. ユーザー ID と API キーを取得し、XMLSTOCK_USER、XMLSTOCK_KEY に設定します（または xmlstock_set_credentials を使用します）。
3. 確認：xmlstock_balance。

注意点（実際の応答で確認済み）：

• 検索結果の強調表示（text_bolds）にはパラメーター hlword=1 を指定します。タグ <hlword> は XML 内にネストされます（stopNodes で解析され、隣接する単語はフレーズに結合されます）。PAA と関連検索には related=1 を指定します（PAA は Google のみ）。
• モバイル検索結果では hlword/PAA/related が返されません — モバイルのスナップショットには順位とスニペットのみが含まれるため、強調表示はデスクトップから取得してください。
• 両方の検索エンジンで結果が 0 件のページがあります。ページ上のオーガニック検索結果が 10 件未満の場合は、サーバーが次のページから自動的に補完します（有料クエリが 1 件追加されます）。
• lr は両方の検索エンジンで Яндекс の地域 ID を受け付けます（XMLStock が Google 用に自動でマッピングします）。
• HTTP 200 + <error code> のエラー：20–25/101/110/111/500 は再試行されます。55 はレート制限のため一時停止します。15 は結果が空（料金は差し引かれます）。31/42 は致命的なエラー（認証）。
• XMLStock に Wordstat はありません — 検索頻度は別のサーバー（Яндекс の公式 Wordstat API）を通じて取得します。

Wordstat（優先度 1）— Яндекс の検索頻度

公式の Wordstat API v2（Yandex Cloud Search API に含まれます）は無料で、申請も OAuth も不要です。https://console.yandex.cloud で一度設定します。

1. フォルダー（folder）を作成するか、既存のものを選び、その ID を WORDSTAT_FOLDER_ID に設定します。
2. search-api.webSearch.user ロールを持つサービスアカウントを作成します。
3. そのアカウント用に、スコープ yc.search-api.execute の API キーを発行し、WORDSTAT_API_KEY に設定します。
4. 確認：任意のフレーズで wordstat_frequency を実行します。

注意点：正確な検索頻度には演算子 "!слово !слово" を使用します（topRequests/regions でサポートされています。dynamics では period=daily の場合のみ）。topRequests のデータは直近 30 日分です。count は文字列で返されます（解析されます）。クォータは 10 rps / 1 時間あたり 100 リクエストです（429 は再試行されますが、大量取得ではスロットリングを設定してください）。associations は最大 20 件です。

Google Search Console（優先度 1）

方法は 2 つあります。推奨は OAuthです。トークンは Google アカウントのアクセス権を引き継ぎ、そのアカウントのすべてのプロパティをまとめて参照できます（今後追加されるものも含みます）。各プロパティにユーザーを追加する必要はありません。

方法 A — OAuth（初回のみ）：

1. https://console.cloud.google.com → プロジェクト → APIs & Services → Library → Google Search Console API を有効にします。
2. OAuth consent screen：External を選び、自分を Test users に追加します。（7 日を超えて有効なリフレッシュトークンを取得するには Publish app をクリックします。認証時に「unverified」という警告が表示されるのは、個人利用では正常です。）
3. Credentials → Create credentials → OAuth client ID → Desktop app → client ID と secret を取得します。
4. チャットで gsc_oauth_start を実行（clientId+secret を渡す）→ リンクを開く → 許可する → ブラウザーが localhost:8585 にリダイレクトし、コードが自動的に取得されます → gsc_oauth_finish を実行します。
5. 確認：gsc_list_sites を実行すると、アカウントのすべてのプロパティが表示されます。

方法 B — サービスアカウント（ヘッドレス cron 用）： IAM → Service Accounts → JSON キー → gsc_save_sa_json（または GSC_SA_JSON にパスを設定）→ 必要な GSC プロパティごとにアカウントのメールアドレスを追加します（設定 → ユーザーと権限、「フル」）。

両方が設定されている場合は、OAuth が優先されます。

Google Analytics 4（優先度 1）

GSC と同じ方法で認証します。OAuth アプリケーションは共通です（GOOGLE_CLIENT_ID／GOOGLE_CLIENT_SECRETを再利用します）。ただし、GA4 独自のスコープが必要なため、別途一度だけ認証してください。

1. 同じプロジェクトで console.cloud.google.com → APIs & Services → Library を開き、Google Analytics Data API と Google Analytics Admin API を有効にします。
2. チャットで ga4_oauth_start を実行します（GSC 用のクライアント ID／シークレットを保存済みの場合は、引数なしで実行できます）→ リンクを開く → 許可する → ブラウザーが localhost:8586 にリダイレクトされます（サーバー同士が競合しないよう、GSC とはポートが異なります）。コードは自動的に取得されます → ga4_oauth_finish を実行します。
3. 確認するには ga4_list_properties を実行します。アカウントのすべてのプロパティとその propertyId が表示されます。
4. デフォルトのプロパティを保存しておくと便利です。ga4_set_credentials で GA4_PROPERTY_ID（手順 3 で確認した数値の ID）を設定します。設定しない場合は、呼び出しのたびに propertyId を渡してください。

方法 B — サービスアカウント： JSON キー → ga4_save_sa_json → GA4 プロパティにアカウントのメールアドレスを追加します（管理者 → プロパティのアクセス管理、役割は「閲覧」）。

Yandex OAuth（ウェブマスター + メトリカ — アプリケーションとトークンは共通）

1. 最初に一度だけ設定します：https://oauth.yandex.ru/client/new → 「ウェブサービス」、リダイレクト URI：https://oauth.yandex.ru/verification_code。権限（スコープ）：Yandex.Webmaster — 「サイト情報の取得」（webmaster:hostinfo）+「サイトの管理」（webmaster:verify）、Yandex.Metrica — 「統計情報の取得」（metrika:read）。ClientID と Client secret を取得します。
2. 以降はチャットで対話的に操作します：ywm_oauth_start（ClientID + secret を渡すと保存されます）→ サイト／カウンターの所有者アカウントでリンクを開く → コードをコピー → ywm_oauth_finish を実行します。ywm と metrika で共通のアクセストークンとリフレッシュトークンが取得され、自動的に更新されます。
3. デフォルト値：YWM_HOST_ID（一覧は ywm_hosts）、METRIKA_COUNTER_ID（一覧は metrika_counters）は、*_set_credentials で設定するか、呼び出しのたびに渡してください。
4. 手動で行う場合：implicit flow（response_type=token）でトークンを取得し、YANDEX_OAUTH_TOKEN に保存します。ただし、リフレッシュされないため期限切れになります（ウェブマスターは約 6 か月、メトリカは約 1 年）。

Yandex API の制限（サーバーの不具合ではありません）：ウェブマスターで URL による絞り込みができるのは query-analytics のみです（データは約 2 週間分）。API v4 には「推奨クエリ」のエンドポイントがありません。ywm_recommended_queries は需要（DEMAND）+ クリック数の不足分を使って近似します。メトリカの検索語句は、暗号化により大部分が「不明」と表示されます。

A-Parser（セルフホスト可能）— SERP と、独自環境を通じた数百種類のパーサー

1. 自分で起動した A-Parser のインスタンス（ライセンス + サーバー）が必要です。このブリッジは管理操作を行いますが、ホストやプロキシは行いません。
2. A-Parser で Settings → API を開き、API サーバーを有効にして、ポート（通常は 9091）とパスワードを確認します。
3. APARSER_URL = http://<IP-инстанса>:<порт>/API（/API パスは必須）、APARSER_PASSWORD = 同じ画面に表示されるパスワード → aparser_set_credentials を実行します。
4. 確認するには aparser_ping、続いて aparser_status を実行します（インスタンスの準備状況と稼働中のプロキシを確認できます）。

注意事項：プロキシとプロキシチェッカー（バッチ）は GUI で一度設定してください。稼働中のプロキシがないと Google／Yandex にすぐブロックされるため、serp／suggest ツールは事前チェックを行って警告します（use_proxy=false は自己責任で使用してください）。プリセットとバッチのデフォルト値は環境変数で設定します（APARSER_GOOGLE_PRESET、APARSER_YANDEX_PRESET、APARSER_PROXY_CHECKERS、APARSER_USE_PROXY）。v1 は同期型かつ読み取り専用です。タスクキューと API の変更系メソッドには対応していません。

日付形式と地域

日付は YYYY-MM-DD（モスクワ時間）です。地域には、よく使われる地域の組み込みリストにある名前（「Москва」、「спб」、「Казахстан」など）または Yandex の数値の地域 ID（213、225 など）を指定します。数値の ID は常に使用できます。カンマ区切りで複数の地域を指定できるのは wordstat サーバーのみです。SERP ツール xmlstock_*／xmlriver_* では地域を 1 つだけ指定できます。ID の完全な一覧は wordstat_regions_tree ツールで確認できます。

使用場所と使用方法

サーバーは、特定のマシンに依存しない通常の stdio プロセスです。利用方法は 4 つあります。

1. Claude Code, локально

Зарегистрировать через claude mcp add --scope user (блок «Регистрация в Claude Code» выше) — доступно во всех проектах и сессиях.

2. Claude Code, другая машина

git clone https://github.com/antohins/seo-tools-mcp.git && cd seo-tools-mcp
pnpm install && pnpm build
# зарегистрировать серверы (блок «Регистрация в Claude Code» выше)
# ключи: скопировать ~/.config/seo-tools-mcp/.env со старой машины (chmod 600)
# ЛИБО выдать в диалоге через <server>_auth_status → <server>_set_credentials

3. Claude Desktop (локально)

В claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/):

{
  "mcpServers": {
    "xmlstock": { "command": "node", "args": ["/ABS/PATH/seo-tools-mcp/servers/xmlstock/dist/index.js"] },
    "wordstat": { "command": "node", "args": ["/ABS/PATH/seo-tools-mcp/servers/wordstat/dist/index.js"] }
  }
}

Ключи подхватятся из ~/.config/seo-tools-mcp/.env автоматически.

4. Удалённо: claude.ai / Claude Code с любого места

claude.ai (web/mobile) умеет только remote MCP (Streamable HTTP по публичному HTTPS). Наши stdio-серверы выносятся на VPS через мост supergateway:

# на сервере: клонировать/собрать как в сценарии 2, ключи в ~/.config/seo-tools-mcp/.env
npx -y supergateway --stateful --outputTransport streamableHttp --port 8801 \
  --stdio "node /opt/seo-tools-mcp/servers/xmlstock/dist/index.js"   # и так для каждого сервера, порты 8801–8805

Дальше nginx: TLS + proxy_pass на 127.0.0.1:880X под секретным путём (например /mcp-<длинный-случайный-токен>/xmlstock/) — supergateway слушать только на localhost. Подключение:

• Claude Code: claude mcp add --transport http xmlstock https://host/<секретный-путь>/xmlstock/mcp
• claude.ai: Settings → Connectors → Add custom connector → тот же URL.

⚠ Секретный путь — минимальный гейт (custom connectors claude.ai не передают произвольные заголовки авторизации). За эндпоинтом — все ключи сервисов, поэтому: только HTTPS, длинный токен в пути, отдельный access-лог.

Альтернатива для Claude Code без HTTP-моста — stdio через ssh:

claude mcp add xmlstock --scope user -- ssh root@SERVER node /opt/seo-tools-mcp/servers/xmlstock/dist/index.js

Разработка

pnpm build        # собрать все воркспейсы
pnpm typecheck    # только типы
pnpm test         # юнит-тесты (vitest, без сети)
pnpm test:live    # лайв-смоук по реальным API (нужны креды в конфиге; free-эндпоинты)
node servers/xmlstock/dist/index.js   # ручной запуск (stdio)

Юнит-тесты покрывают чистую логику: маскирование секретов, классификацию OAuth-ошибок, пагинацию Метрики/GSC (дедуп, truncated), фильтры, парсер SERP, регионы. Лайв-смоук поднимает каждый сервер и дёргает бесплатный инструмент (xmlstock_balance, xmlriver_balance, wordstat_frequency, gsc_list_sites, ywm_hosts, metrika_counters, aparser_ping) — проверка авторизации end-to-end.

Общий код (shared/): HTTP-клиент с ретраями на 429/5xx (3 попытки, экспоненциальный backoff, Retry-After), загрузчик env + персистентный конфиг, фабрика auth-инструментов, Яндекс-OAuth с авто-refresh, JSON-хелперы MCP, счётчик расхода платных вызовов. XMLStock дополнительно ретраит свои «временные» коды из тела XML, код 15 («ничего не найдено») трактуется как пустая выдача.

Сборка серверов — tsup: shared/ вбивается в единый dist/index.js каждого сервера (рантайм-зависимости остаются external), поэтому npm-пакет самодостаточен.

Публикация в npm (мейнтейнерам)

Каждый сервер публикуется как отдельный пакет seo-tools-mcp-<сервер>; shared/ приватный и в npm не уходит (вбит в серверы). Версии всех серверов держим синхронно.

npm login
pnpm -r build                 # shared (tsc) → серверы (tsup-бандл)
pnpm -r publish --access public   # публикует 8 серверов; private-пакеты (shared, корень) пропускаются

pnpm publish сам подставляет реальные версии вместо workspace:* и не даст опубликовать при грязном рабочем дереве.

Бамп версии — только через корневой package.json: правишь версию там и запускаешь pnpm version:sync, который разносит её по всем 42 местам (package.json и server.json каждого сервера, литерал в new McpServer({ version }), манифесты плагинов). pnpm -r exec npm version patch для этого НЕ годится: он обновит только пакеты серверов, остальное останется на старой версии, и pnpm version:check в CI упадёт. Проверить без записи — pnpm version:check.

Контрибьютинг

PR приветствуются — см. CONTRIBUTING.md. История изменений — CHANGELOG.md. Уязвимости — приватно через Security Advisories (детали — SECURITY.md).

Лицензия

MIT © antohins