seo-tools-mcp

Русский | Английский

Восемь общепроизводительных stdio MCP серверов для SEO: доступ к SERP, Wordstat, Google Search Console, Google Analytics 4, Yandex.Webmaster, Yandex.Metrica и self-hosted A-Parser прямо из Claude Code (или любого MCP клиента). Все инструменты — только для чтения — ничего не публикуется и не изменяется в ваших аккаунтах — и вывод представлен в строгом JSON. Это задокументировано в машинно-читаемой форме через аннотацию readOnlyHint, которая намеренно отсутствует у двадцати инструментов, чьи каждый вызов расходует ресурс с учетом тарифа (XMLStock/XMLRiver-запросы, трафик прокси A-Parser): иначе клиент распознавал бы их как безобидные и просил бы подтверждения перед запуском по большому пулу ключевых слов. Не привязано к конкретному сайту: значения по умолчанию (GSC property, GA4 property, Webmaster host, Metrica counter) конфигурируются на лету.

🛰 Мы используем эти сервера в продакшене у 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 key
xmlriver	xmlriver_serp, xmlriver_images, xmlriver_news, xmlriver_maps, xmlriver_check_index, xmlriver_suggest, xmlriver_related_questions, xmlriver_balance	API key
wordstat	wordstat_frequency, wordstat_dynamics, wordstat_regions, wordstat_regions_tree	Api-Key Yandex Cloud
gsc	gsc_query, gsc_inspect_url, gsc_list_sites, gsc_get_site, gsc_list_sitemaps, gsc_get_sitemap	OAuth (all account properties) / service account
ga4	ga4_list_properties, ga4_metadata, ga4_check_compatibility, ga4_report, ga4_bytime, ga4_traffic_sources, ga4_geo, ga4_devices, ga4_top_pages, ga4_events, ga4_realtime, ga4_funnel, ga4_annotations, ga4_property_details	OAuth (all account properties) / service account
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 (auto-refresh)
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 (auto-refresh)
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	self-hosted A-Parser (API URL + password)

Региональная фокусировка: XMLStock охватывает SERP как Google, так и Yandex, тогда как Wordstat, Webmaster и Metrica — сервисы Yandex; этот набор наиболее полезен для SEO на рынке России/СНГ (хотя GSC и Google-составная часть XMLStock глобальны).

Опубликовано на: npm (восемь пакетов), официальный MCP Registry, GitHub MCP Registry (все восемь серверов), рынок Claude Code (ниже) и .mcpb-бандлы в releases.

Каждый сервер дополнительно предоставляет инструменты аутентификации <server>_auth_status и <server>_set_credentials (см. Interactive authorization).

Инструменты по серверу

xmlstock — Google/Yandex SERP

xmlstock_serp — SERP Google/Yandex веб (органика + подсветка + SERP features): регион, устройство, безопасный поиск, сортировка (Yandex), временной диапазон, рекламные блоки; третий движок yandex_xml — официальный Yandex XML (группировка до 100 за один запрос, подсветка hlword на любом устройстве, статистика найденных документов; ставка от 24 ₽/1000)
xmlstock_images — поиск изображений Google (URL страницы + URL изображения + заголовок)
xmlstock_news — новости Google (заголовок, источник, дата, сниппет)
xmlstock_video — видеоданные Google (URL, заголовок, изображение, источник, канал, продолжительность)
xmlstock_wordstat — Yandex Wordstat: топовые и связанные запросы с частотами (региональная привязка), операторы Wordstat
xmlstock_wordstat_dynamics — частота во времени (день/неделя/месяц)
xmlstock_wordstat_regions — региональное распределение с индексом affinity и разрешёнными названиями регионов
xmlstock_wordstat_regions_tree — дерево регионов Wordstat (id + название)
xmlstock_balance — баланс аккаунта / проверка ключа (бесплатно)

Wordstat через XMLStock использует тот же ключ XMLSTOCK_*, что и для SERP — настройка Yandex Cloud не требуется (в отличие от автономного сервера wordstat).

xmlriver — SERP Google/Yandex + индексация

xmlriver_serp — органическая SERP Google/Yandex (глубина собирается пагинацией: каждый 10 позиций = 1 платный запрос), флаг наличия AI-обзора; опция includeAIOverview — полный текст AI Overview + процитированные ссылки (платный ai=1, только Google); includeAdditional — дополнительные блоки SERP Google из <addresults> (knowledge_graph, localresultsplace, rs и пр.; содержимое блоков зависит от платных опций в панели XMLRiver; отсутствующие блоки перечислены в additional.unavailable); гео-таргетинг Google — location (город → loc, "Москва"/"1011969") и country (ISO/числовой идентификатор, автоматически определяется по городу); device — desktop/mobile/tablet, os (ios/android) отправляется только с device=mobile
xmlriver_images — поиск изображений Google (URL страницы + URL изображения + заголовок + источник + размер)
xmlriver_news — Google новости (заголовок, источник, дата, сниппет), фильтр по времени; гео через location/country
xmlriver_maps — поиск мест Google Maps (setab=maps, обязательные параметры zoom 1–15 и coords "lat,lng", count 5–50): заголовок, рейтинг, адрес, телефон, удобства, координаты, place_id, число отзывов. Примечание: формат — по документации, не верифицирован в реальном времени (эндпойнт стабильно возвращает ошибку 500 на тестовом аккаунте — может потребоваться платный приборной панели)
xmlriver_check_index — проверить, индексирован ли URL в Google/Yandex (inindex)
xmlriver_suggest — подсказки к поиску Google (до 50 фраз за вызов, тарифицируются за фразу); гео через location/country
xmlriver_related_questions — блок Google "People Also Ask" (вопросы всегда возвращаются; ответы — только если включён платный вариант "Related Questions with answers" в панели XMLRiver)
xmlriver_balance — баланс аккаунта / проверка ключа (бесплатно)

wordstat — частоты ключевых слов Yandex

wordstat_frequency — широкие и точные частоты, уточняющие запросы (связанные) и ассоциации
wordstat_dynamics — частота во времени (ежедневно/еженедельно/ежемесячно)
wordstat_regions — региональное распределение с индексом affinity и разрешёнными названиями регионов
wordstat_regions_tree — полное дерево регионов Wordstat (id + название)

gsc — Google Search Console

gsc_query — Search Analytics (клики/покрытия/CTR/позиция), автопагинация, dataState финальные/все, произвольные фильтры по измерениям (filters, AND-логика) и aggregationType (auto/byProperty/byPage)
gsc_inspect_url — URL Inspection: статус индексации,Coverage, canonical, last crawl, мобильная пригодность, богатые результаты
gsc_list_sites — свойства, доступные авторизации
gsc_get_site — уровень доступа к свойству
gsc_list_sitemaps — отправленные карты сайта с их статусом
gsc_get_sitemap — детали одной карты сайта

Даты Analytics поиска представлены в часовом поясе Pacific Time (не MSK); история примерно 16 месяцев; финальные данные задерживаются примерно на 2–3 дня (свежие данные через dataState=all); ctr в ответе — от 0 до 1.

ga4 — Google Analytics 4

ga4_list_properties — свойства GA4, доступные для авторизации (здесь берётся propertyId — это не G-XXXXXXX)
ga4_metadata — измерения и метрики, доступные в ЭТОМ свойстве, включая пользовательские (customEvent:…); поиск подстроки, blockedReasons (такая метрика возвращает нули) и type (int vs float для metricFilters)
ga4_check_compatibility — совместим ли набор измерение/метрика с данным свойством, без выполнения тяжёлого отчёта; при ошибке перечисляет поля для удаления
ga4_report — произвольный отчёт: любые измерения × метрики, фильтры по измерениям, сортировка (полный Data API runReport)
ga4_bytime — метрики по времени (дата/час/неделя/месяц)
ga4_traffic_sources — сегментация по источнику/каналу, кампания; 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) и потоки данных с их G-XXXXXXX идентификаторами измерений

Единицы и даты: GA4 возвращает bounceRate/engagementRate в виде дроби от 0 до 1, а не в процентах; даты резолвятся в временной зоне свойства — передавайте YYYY-MM-DD или ключевые слова GA4 (today, yesterday, 28daysAgo), применённая временная зона возвращается в ответе. Ответы содержат totalRows/truncated, а thresholded: true означает, что часть данных скрыта из-за политики приватности GA4.

ywm — Yandex.Webmaster

ywm_hosts — идентификатор пользователя + подтверждённые сайты
ywm_summary — SQI, страницы в поиске, исключённые, проблемы сайта по уровню
ywm_search_queries — аналитика запросов по URL (~2 недели по умолчанию; можно задать dateFrom/dateTo)
ywm_queries_history — суммарные показы/клики/позиции во времени
ywm_recommended_queries — приблизительно рекомендуемые запросы (спрос + дефицит кликов)
ywm_popular — популярные запросы хоста
ywm_indexing_history — страницы в поиске во времени
ywm_sqi_history — SQI во времени
ywm_external_links — выборка внешних ссылок + общее число
ywm_broken_links — сломанные внутренние/внешние ссылки
ywm_diagnostics — проблемы сайта
ywm_important_urls — отслеживаемые URL с индексированием/поиск статус
ywm_sitemaps — карты сайтов с статусами

metrika — Yandex.Metrica

metrika_report — произвольный отчёт: любые измерения × метрики, фильтры, сортировка (полноценный Stat API)
metrika_bytime — метрики по времени (день/неделя/месяц/час)
metrika_traffic_sources — визиты/пользователи/показатель отказов по источнику трафика
metrika_geo — визиты по стране/региону/городу
metrika_devices — визиты по устройствам/OS/браузерам
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 — живые прокси на экземпляре (фильтруются по пакам проверки прокси; учётные данные прокси никогда не показываются)
aparser_parsers — парсеры, установленные на экземпляре
aparser_parser_fields — поля результата, которые может возвращать парсер (плоские + массивы)
aparser_get_preset — прочитать параметры конфигурации preset'а (существенные значения замаскированы)
aparser_serp_google — Google organic SERP (SE::Google); прокси включены по умолчанию + пре-провал прокси
aparser_serp_yandex — Yandex organic SERP (SE::Yandex); регион через lr
aparser_suggest — подсказки к поиску Google/Yandex
aparser_request — универсальный синхронный запрос к любому парсеру (oneRequest)
aparser_bulk_request — пакетный запрос: один парсер, много запросов, N потоков (bulkRequest)

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

Quick start

Вариант 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 (marketplace)

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

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, который устанавливает все восемь сразу. Бандл удобен, но в каждой сессии занимает ~110 токенов: если вы работаете только с Webmaster и Metrika, можно установить эти два плагина.

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

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

Поля, помеченные как чувствительные (API-ключи, OAuth-секреты) попадают в OS keychain и никогда не попадают в settings.json. OAuth-плагинам (gsc, ga4, ywm, metrika) достаточно зарегистрировать клиент-id/секрет однажды — вход выполняется в чате через <server>_oauth_start → <server>_oauth_finish.

Каждый плагин также поставляет набор skills — процедурные заметки по его источнику данных: как не сжечь баланс при отслеживании позиций, почему broad frequency у Wordstat переоценит трафик в несколько раз, что заставляет GA4 возвращать нули, как усреднённая позиция GSC отличается от реальной, полученной с SERP. Они стоят примерно ~110 токенов в контексте и расширяются только по мере необходимости.

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

Каждый сервер — самостоятельный npm-пакет seo-tools-mcp-<server>; добавьте его одной командой:

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	Google/Yandex SERP + Wordstat
seo-tools-mcp-xmlriver	Google/Yandex SERP + индексация
seo-tools-mcp-wordstat	Частоты ключевых слов Yandex (Yandex Cloud)
seo-tools-mcp-gsc	Google Search Console
seo-tools-mcp-ga4	Google Analytics 4
seo-tools-mcp-ywm	Yandex.Webmaster
seo-tools-mcp-metrika	Yandex.Metrica
seo-tools-mcp-aparser	мост к 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 URL (npm i github:antohins/seo-tools-mcp) не поддерживается: это pnpm-монорепо, и отдельную подпакетную сборку установить нельзя. Чтобы установить из исходников, используйте Option 4 ниже (клонирование + сборка). Готовые пакеты есть на 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_set_credentials и сохранит. После этого просто отвечайте обычным языком: "получить top-10 Yandex по запросу X", "частоты ключевых слов для …", "клики/покрытия из GSC за месяц". Ключи и OAuth настраиваются один раз (см. Getting access per-service).

Interactive authorization (любая сессия)

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

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

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

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

Multi-account

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

У каждого инструмента есть необязательный параметр 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 и одно приложение Яндекса обслуживают все профили (создайте клиента один раз, авторизуйте столько раз, сколько нужно). Только токены хранятся по каждому аккаунту; обновление токена относится к своему профилю.
Разрешение строгое: account="clientX" без настроенных ключей — ошибка со списком доступных профилей (без скрытого переноса в чьей-либо аккаунт). Значения по умолчанию (GSC_SITE_URL__clientX, YWM_HOST_ID__clientX, METRIKA_COUNTER_ID__clientX) — тоже по аккаунтам.
<server>_auth_status показывает все профили и их ключи (замаскированы).
Для полного изоляции: отдельный файл окружения через SEO_TOOLS_MCP_ENV (при установке значение окружения не читается домашним конфигом).

Установка

cd seo-tools-mcp
pnpm install
pnpm build

Секреты

Один файл окружения: ~/.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}).

Getting access (per service)

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

XMLStock — Google + Yandex SERP

Зарегистрируйтесь на https://xmlstock.com → дашборд, пополните баланс (Google XML и Yandex Live — от ~12 руб./1000 запросов).
Возьмите user ID и API key → XMLSTOCK_USER, XMLSTOCK_KEY (или через xmlstock_set_credentials).
Проверьте: xmlstock_balance.

Примечания (проверено по живым ответам):

Подсветка в SERP (text_bolds) — параметр hlword=1, тег <hlword> как вложенный XML (разбор через stopNodes, соседние слова объединяются в фразы); PAA и related searches — related=1 (PAA только для Google);
мобильная SERP не возвращает hlword/PAA/related — мобильная снимка содержит только позиции и сниппеты; для подсветки используйте десктоп;
страницы начинаются с 0 для обоих движков; органические результаты на одной странице может быть менее чем 10 — сервер дополняет дополнительной страницей (+1 платный запрос);
lr принимает региональные идентификаторы Yandex для обоих движков (XMLStock отображает их на Google);
ошибки приходят как HTTP 200 + <error code>: 20–25/101/110/111/500 повторяются повторно, 55 — ограничение скорости с паузой, 15 = пустой SERP ( charges), 31/42 — фатальные (auth);
Wordstat недоступен через XMLStock — частотности проходят через отдельный сервер (официальный API Wordstat от Yandex).

Wordstat — частоты ключевых слов Yandex

Официальный Wordstat API v2 (часть Yandex Cloud Search API) — бесплатно, без формы заявок и OAuth. Один раз в https://console.yandex.cloud:

Создайте папку (или используйте существующую) → её ID добавьте в WORDSTAT_FOLDER_ID.
Создайте сервис-аккаунт с ролью search-api.webSearch.user.
Выдайте API-ключ с областью yc.search-api.execute → WORDSTAT_API_KEY.
Проверьте: wordstat_frequency для любой фразы.

Примечания: точная частота записывается как операторов "!word !word" (поддерживаются в topRequests/regions; в dynamics — только при period=daily); данные topRequests за последние 30 дней; count приходит строками (разбор); квоты — 10 rps / 100 запросов в час (429 повторяются, но плановый лимит для пакетной загрузки). Ассоциации максимум 20.

Google Search Console

Два пути; рекомендуемое — OAuth: токен наследуется вашей учетной записью Google и видит ВСЕ её свойства GSC сразу (включая будущие), отдельного приглашения пользователей к каждому свойству не требуется.

Путь А — OAuth (один раз):

https://console.cloud.google.com → проект → APIs & Services → Library → включить Google Search Console API.
Экран согласия OAuth: External; добавьте себя в Test users. (Для длительного срока обновления токена — нажмите Publish app; предупреждение об "unverified" нормальное для личного использования.)
Credentials → Create credentials → OAuth client ID → Desktop app → возьмите client ID и секрет.
В чате: gsc_oauth_start (передайте clientId+secret) → откройте ссылку → предоставьте доступ → браузер перенаправит на localhost:8585, код считывается автоматически → gsc_oauth_finish.
Проверьте: gsc_list_sites — показывают все свойства аккаунта.

Путь Б — сервисный аккаунт (для headless-crons): IAM → Service Accounts → JSON key → `gsc_save_sa_json` (или путь в `GSC_SA_JSON`) → добавьте email учётной записи ко всем нужным свойствам GSC (Settings → Users and permissions, "Full").

Если оба варианта настроены — OAuth берет верх.

Google Analytics 4

Аналогично двум путям у GSC, и OAuth-приложение общее (GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET повторно используются). У GA4 свой scope, поэтому нужен собственный разовый доступ.

В том же Cloud проекте → APIs & Services → Library → включить Google Analytics Data API и Google Analytics Admin API.
В чате: ga4_oauth_start (если клиент-id/секрет уже сохранены для GSC — аргументы не требуются) → откройте ссылку → предоставьте доступ → перенаправление на localhost:8586 (раз используется другой порт), код подхватывается автоматически → ga4_oauth_finish.
Проверьте: ga4_list_properties — отображает все свойства аккаунта и их propertyId.
Удобно: сохраните дефолтное свойство через ga4_set_credentials → GA4_PROPERTY_ID (числовой идентификатор из шага 3), иначе передавайте propertyId в каждом вызове.

Путь Б — сервисный аккаунт: JSON key → `ga4_save_sa_json` → добавьте email учётной записи к свойству GA4 (Admin → Property access management, "Viewer").

Яндекс OAuth (Webmaster + Metrica — один приложение, один токен)

Один раз: https://oauth.yandex.ru/client/new → "Web services", Redirect URI: https://oauth.yandex.ru/verification_code. Скоупы: Yandex.Webmaster — "Get information about sites" (webmaster:hostinfo) + "Manage sites" (webmaster:verify); Yandex.Metrica — "Get statistics" (metrika:read). Запишите ClientID и Client secret.
Затем в чате: ywm_oauth_start (передайте ClientID + secret, они сохраняются) → откройте ссылку под учётной записью, владеющей сайтом/счётчиком → скопируйте код → ywm_oauth_finish. Вы получите доступ и токены-refresh, общие для ywm и metrika; обновление производится автоматически.
Значения по умолчанию: YWM_HOST_ID (для ywm_hosts), METRIKA_COUNTER_ID (для metrika_counters) — задаются через *_set_credentials, или передаются в каждом вызове.
Ручной слот: можно получить implicit-flow токен (response_type=token) и сохранить в YANDEX_OAUTH_TOKEN — но без обновления он истекает (Webmaster ~6 месяцев, Metrica ~1 год).

Ограничения API Яндекса (не баги сервера): фильтрация URL в Webmaster доступна только в аналитике запросов (данные ~2 недели); в API v4 нет эндпоинта "рекомендованные запросы" — ywm_recommended_queries приближает спрос + дефицит кликов; поисковые фразы в Metrica чаще не определены (зашифрованы).

A-Parser (самостоятельный) — SERP и сотни парсеров через ваш собственный бокс

Ваш собственный запущенный A-Parser экземпляр (лицензия + сервер) — мост управляет им, но не размещает и не проксирует его.
В A-Parser: Settings → API — включите API-сервер, запомните порт (обычно 9091) и пароль.
APARSER_URL = http://<instance-IP>:<port>/API (путь /API обязателен), APARSER_PASSWORD = тот же пароль → aparser_set_credentials.
Проверьте: aparser_ping, затем aparser_status (готовность инстанса + живые прокси).

Примечания: прокси и наборы прокси (packs) настраиваются в GUI — без живых прокси сервисы Google/Yandex будут банить, поэтому serp/suggest работают после предпросмотра; дефолтные пресеты и паки можно настроить через env (APARSER_GOOGLE_PRESET, APARSER_YANDEX_PRESET, APARSER_PROXY_CHECKERS, APARSER_USE_PROXY); v1 — синхронный и read-only: очередь задач и мутирующие API-методы не привязаны.

Формат дат и регионы

Даты — YYYY-MM-DD (MSK). Регионы: название из встроенного списка обычных регионов ("Москва", "спб", "Казахстан"…) или числовой идентификатор региона Yandex (213, 225…) — числовой ID всегда работает. Списки регионов через запятую поддерживаются только сервером wordstat; у xmlstock_*/xmlriver_* SERP-инструменты принимают ОДИН регион. Полный каталог идентификаторов — инструмент wordstat_regions_tree.

Где и как использовать

Сервера — это обычные процессы stdio и не привязаны к конкретной машине. Четыре сценария:

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

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

2) Claude Code, на другой машине

_auth_status → _set_credentials:

git clone https://github.com/antohins/seo-tools-mcp.git && cd seo-tools-mcp
pnpm install && pnpm build
# зарегистрируйте серверы (блок "Registering in 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) поддерживает только удалённый 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-<длинный-token>/xmlstock/) — пусть supergateway слушает только на localhost. Подключение:

Claude Code: claude mcp add --transport http xmlstock https://host/<secret-path>/xmlstock/mcp
claude.ai: Настройки → Подключения → Добавить собственный коннектор → тот же URL.

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

Альтернатива 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 (требуются креды в конфиге; бесплатные API)
node servers/xmlstock/dist/index.js   # ручной прогон (stdio)

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

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

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

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

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

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

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

Обновляйте версию только в корневом package.json, затем выполняйте pnpm version:sync — она распространяется на все 42 места (каждый server-пакет и 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).