SEO Tools: XMLRiver SERP (Google + Yandex)

seo-tools-mcp

俄语 | 英语

八个用于 SEO 的通用 stdio MCP 服务：可直接从 Claude Code（以及任何 MCP 客户端）访问 SERP、Wordstat、Google Search Console、Google Analytics 4、Yandex.Webmaster、Yandex.Metrica 和可自托管的 A-Parser。所有工具均为只读——不会在你的账号中发布或更改任何内容，输出为严格的 JSON。机器可读的只读状态通过 readOnlyHint 注解声明；对于二十个每次调用都会消耗付费资源的工具（XMLStock/XMLRiver 请求、A-Parser 代理流量），我们故意不添加该注解——否则客户端会认为这些工具无害，在对大型池运行任务前不再询问确认。它们不绑定到具体网站：默认值（GSC 属性、GA4 属性、Webmaster 主机、Metrica 计数器）均可随时配置。

🛰 我们在生产环境中使用这些服务于 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（账号的所有属性）/ service account
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（账号的所有属性）/ 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（自动刷新）
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（八个软件包）、官方 MCP Registry、GitHub MCP Registry（全部八个服务）、Claude Code 插件市场（见下文），以及 发布版本中的 .mcpb 捆绑包。

每个服务还提供身份验证工具 <server>_auth_status 和 <server>_set_credentials（参见在任意会话中进行交互式身份验证）。

按服务划分的工具

xmlstock — Google/Яндекс SERP

• xmlstock_serp — Google/Яндекс网页搜索结果（自然结果 + 高亮 + SERP 功能）：地区、设备、安全搜索、排序（Яндекс）、时间范围、广告区块；第三个引擎 yandex_xml 是官方 Яндекс XML（每次请求最多 groupby 100，任何设备均支持 hlword，可查询 found/found-docs 统计数据；价格从 24 ₽/1000 次起）
• xmlstock_images — Google 图片搜索（页面 URL + 图片 URL + 标题）
• xmlstock_news — Google 新闻（标题、来源、日期、摘要）
• xmlstock_video — Google 视频（URL、标题、预览图、主机、频道、时长）
• xmlstock_wordstat — Яндекс 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/Яндекс SERP + 索引检查

• xmlriver_serp — Google/Яндекс 自然搜索结果（通过分页获取更多结果：每 10 个位置 = 1 次付费请求），AI Overview 可用标记；选项 includeAIOverview — AI Overview 完整文本 + 引用链接（付费 ai=1，仅限 Google）；includeAdditional — Google 额外 SERP 区块，来自 <addresults>（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 — 检查 URL 是否已被 Google/Яндекс 收录（inindex）
• xmlriver_suggest — Google 搜索建议（每次调用最多 50 个短语，每个短语均收费）；建议的地理定位 — location/country
• xmlriver_related_questions — Google“相关问题”/People Also Ask 区块（始终返回问题；仅在账户中启用了付费选项“带答案的 Related Questions”时才返回答案）
• xmlriver_balance — 账户余额 / 密钥检查（免费）

wordstat — Яндекс 搜索频率

• 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 — 单个 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 — 设备类型/操作系统/浏览器
• 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“令牌”以及每小时/每日剩余量。

单位和日期：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（只有 Google 提供 PAA）；
• 移动端搜索结果不返回 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. 为其创建一个API 密钥，作用域为 yc.search-api.execute → WORDSTAT_API_KEY。
4. 检查：使用任意短语调用 wordstat_frequency。

注意事项：精确频率 = 运算符 "!слово !слово"（topRequests/regions 支持；dynamics 中仅在 period=daily 时支持）；topRequests 数据涵盖最近 30 天；count 以字符串形式返回（可解析）；配额为 10 rps / 每小时 100 次请求（429 会重试，但批量获取时需设置限流）；associations 最多 20 条。

Google Search Console（优先级 1）

有两种方式；推荐使用 OAuth：令牌会继承你的 Google 账号权限，并能一次查看该账号的所有 GSC 资源（包括未来添加的资源），无需将用户添加到每个资源中。

方式 A — OAuth（只需设置一次）：

1. https://console.cloud.google.com → 项目 → APIs & Services → Library → 启用 Google Search Console API。
2. OAuth consent screen：类型选 External；将自己添加到 Test users。（如需 refresh token 有效期超过 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 有自己的 scope，因此需要单独授权一次。

1. 在同一个项目中，前往 console.cloud.google.com → APIs & Services → Library → 启用 Google Analytics Data API 和 Google Analytics Admin API。
2. 在聊天中调用：ga4_oauth_start（如果已为 GSC 保存 client ID/secret，则无需提供参数）→ 打开链接 → 授权 → 浏览器将重定向到 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 属性中（管理员 → 资源访问管理，角色为“查看者”）。

Яндекс OAuth（Вебмастер + Метрика — 一个应用，一个令牌）

1. 一次性设置：https://oauth.yandex.ru/client/new → “Web 服务”，Redirect URI：https://oauth.yandex.ru/verification_code。权限（scope）：Яндекс.Вебмастер — “获取网站信息”（webmaster:hostinfo）+“管理网站”（webmaster:verify）；Яндекс.Метрика — “获取统计信息”（metrika:read）。获取 ClientID 和 Client secret。
2. 后续在聊天中交互操作：ywm_oauth_start（传入 ClientID + secret，这些信息会被保存）→ 使用网站/计数器所有者的账号打开链接 → 复制代码 → ywm_oauth_finish。将获得 ywm 和 metrika 共用的 access+refresh 令牌；令牌会自动刷新。
3. 默认值：YWM_HOST_ID（列表 — ywm_hosts）、METRIKA_COUNTER_ID（列表 — metrika_counters）— 通过 *_set_credentials 设置，或在每次调用时传入。
4. 手动替代方式：获取 implicit-flow 令牌（response_type=token）并保存到 YANDEX_OAUTH_TOKEN — 但由于没有 refresh，令牌会过期（Вебмастер 约 6 个月，Метрика 约 1 年）。

Яндекс API 的限制（并非服务端问题）：Вебмастер 中仅 query-analytics 支持按 URL 筛选（数据约为 2 周）；API v4 没有“推荐查询”端点 — ywm_recommended_queries 会通过需求（DEMAND）+ 点击量不足进行估算；Метрика 中的搜索词大多显示为“未定义”（由于加密）。

A-Parser（可自托管）— 通过自己的实例获取 SERP 和数百种解析器

1. 自行运行一个 A-Parser 实例（许可证 + 服务器）— 桥接服务会对其进行管理，但不会托管或代理该实例。
2. 在 A-Parser 中：设置 → API — 启用 API 服务器，记下端口（通常为 9091）和密码。
3. APARSER_URL = http://<IP-инстанса>:<порт>/API（必须包含路径 /API），APARSER_PASSWORD = 同处显示的密码 → aparser_set_credentials。
4. 检查：aparser_ping，然后运行 aparser_status（实例就绪状态 + 可用代理）。

注意事项：代理和代理检查器（批次）需在 GUI 中一次性配置 — 没有可用代理时，Google/Яндекс 会很快封禁请求，因此 serp/suggest 工具会进行 preflight 检查并发出警告（use_proxy=false — 风险自负）；默认预设和批次通过 env 设置（APARSER_GOOGLE_PRESET、APARSER_YANDEX_PRESET、APARSER_PROXY_CHECKERS、APARSER_USE_PROXY）；v1 为同步且只读 — 未接入任务队列和 API 的变更方法。

日期格式和地区

日期格式为 YYYY-MM-DD（莫斯科时间）。地区：使用内置常用地区列表中的名称（“Москва”、“спб”、“Казахстан”等）或 Яндекс 地区的数字 ID（213、225 等）— 数字 ID 始终有效。只有 wordstat 服务支持以逗号分隔的多个地区；SERP 工具 xmlstock_*/xmlriver_* 只接受一个地区。完整的 ID 参考列表见工具 wordstat_regions_tree。

在哪里以及如何使用

服务是普通的 stdio 进程，不绑定特定机器。共有四种使用场景：

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