seo-tools-mcp

<p align="center">
  <img src="assets/logo-128.png" width="96" height="96" alt="seo-tools-mcp" />
</p>

# seo-tools-mcp

[![CI](https://github.com/antohins/seo-tools-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/antohins/seo-tools-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**Русский** | [English](README.en.md)

Шесть **универсальных** stdio MCP-серверов для SEO: доступ к SERP, Wordstat, Google Search Console, Яндекс.Вебмастеру и Яндекс.Метрике прямо из Claude Code (и любого MCP-клиента). Все инструменты **read-only**, вывод — строгий JSON. К конкретному сайту не привязаны: дефолты (свойство GSC, хост Вебмастера, счётчик Метрики) настраиваются на лету.

> 🛰 Эти серверы мы используем в продакшене в **[PBN Workers](https://pbn-workers.com/ru/tools/seo-tools-mcp/)** — инфраструктура поискового топа: семантика, PBN и сателлиты, автоматизация SEO. Нужен стабильный органический трафик — [приходите](https://pbn-workers.com/ru/tools/seo-tools-mcp/).

| Сервер | Рабочие инструменты | Авторизация |
|---|---|---|
| `xmlstock` | `xmlstock_serp`, `xmlstock_images`, `xmlstock_news`, `xmlstock_video`, `xmlstock_balance` | API-ключ |
| `xmlriver` | `xmlriver_serp`, `xmlriver_images`, `xmlriver_news`, `xmlriver_check_index`, `xmlriver_balance` | API-ключ |
| `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 (все свойства аккаунта) / 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 (авто-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 (авто-refresh) |

У каждого сервера дополнительно есть auth-инструменты `<server>_auth_status` и `<server>_set_credentials` (см. [Интерактивная авторизация](#интерактивная-авторизация-в-любой-сессии)).

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

### xmlstock — SERP Google/Яндекс
- `xmlstock_serp` — веб-выдача Google/Яндекса (органика + подсветки + SERP-фичи): регион, устройство, safe search, сортировка (Яндекс), период, рекламные блоки
- `xmlstock_images` — поиск картинок Google (url страницы + url изображения + заголовок)
- `xmlstock_news` — новости Google (заголовок, источник, дата, сниппет)
- `xmlstock_video` — видео Google (url, заголовок, превью, хост, канал, длительность)
- `xmlstock_balance` — баланс аккаунта / проверка ключа (бесплатно)

### xmlriver — SERP Google/Яндекс + проверка индексации
- `xmlriver_serp` — органика Google/Яндекса, глубина одним запросом (groupby до 100), флаг наличия AI Overview
- `xmlriver_images` — картинки Google (страница + url картинки + заголовок + источник + размеры)
- `xmlriver_news` — новости Google (заголовок, источник, дата, сниппет), фильтр по времени
- `xmlriver_check_index` — проверка индексации URL в Google/Яндексе (`inindex`)
- `xmlriver_balance` — баланс аккаунта / проверка ключа (бесплатно)

### wordstat — частотности Яндекса
- `wordstat_frequency` — широкая и точная частотность, уточняющие запросы (related) и ассоциации
- `wordstat_dynamics` — частотность по времени (день/неделя/месяц)
- `wordstat_regions` — распределение по регионам с индексом аффинити и именами регионов
- `wordstat_regions_tree` — полное дерево регионов Вордстата (id + имя)

### gsc — Google Search Console
- `gsc_query` — Search Analytics (клики/показы/CTR/позиция), авто-пагинация, `dataState` final/all
- `gsc_inspect_url` — URL Inspection: статус индексации, покрытие, canonical, последний обход, mobile usability, rich results
- `gsc_list_sites` — свойства, доступные авторизации
- `gsc_get_site` — уровень доступа к свойству
- `gsc_list_sitemaps` — отправленные sitemap со статусом
- `gsc_get_sitemap` — детали одного sitemap

### ywm — Яндекс.Вебмастер
- `ywm_hosts` — id пользователя + подтверждённые сайты
- `ywm_summary` — ИКС, страниц в поиске, исключено, проблемы сайта по важности
- `ywm_search_queries` — аналитика запросов по URL (~2 недели)
- `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` — топ органических посадочных

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

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

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

```bash
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 ywm      --scope user -- npx -y seo-tools-mcp-ywm
claude mcp add metrika  --scope user -- npx -y seo-tools-mcp-metrika
```

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

```bash
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 ywm metrika; 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` (при заданном пути домашний конфиг НЕ читается).

## Установка

```bash
cd seo-tools-mcp
pnpm install
pnpm build
```

## Секреты

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