mcp-yandex-webmaster

# Яндекс Вебмастер MCP

[![npm](https://img.shields.io/npm/v/mcp-yandex-webmaster)](https://www.npmjs.com/package/mcp-yandex-webmaster)
[![CI](https://github.com/askads/mcp-yandex-webmaster/actions/workflows/ci.yml/badge.svg)](https://github.com/askads/mcp-yandex-webmaster/actions/workflows/ci.yml)
[![Glama](https://glama.ai/mcp/servers/askads/mcp-yandex-webmaster/badges/score.svg)](https://glama.ai/mcp/servers/askads/mcp-yandex-webmaster)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)

**Яндекс Вебмастер MCP** подключает AI-приложение — Claude, Cursor, Codex и другие — к данным Яндекс Вебмастера. Спросите на естественном языке, как сайт выглядит в поиске Яндекса: какие страницы попали или не попали в поиск, что происходит с показами и кликами, какие проблемы видит Вебмастер, как устроены sitemap и внешние ссылки. Подключение начинается прямо в диалоге: не нужно заранее создавать токен или редактировать конфигурацию.

- **20 инструментов.** Сайты, диагностика, поисковые запросы, индексация, sitemap, внешние ссылки и подключение аккаунта прямо из диалога.
- **Работает с органическим поиском.** Это не Метрика, не Вордстат и не рекламный кабинет: здесь нет данных о посещаемости, поисковом спросе и рекламе.
- **Подключение в чате.** Яндекс откроет страницу входа; одноразовый код действует 10 минут, а сервер проверит доступ к сайтам сразу после подключения.
- **Почти всё — чтение.** Отдельные инструменты могут добавить сайт или sitemap, запустить подтверждение прав либо поставить страницу в очередь на переобход.
- **Только ваши сайты.** Сервер видит данные тех сайтов, к которым у токена есть доступ; для статистики и диагностики права на сайт должны быть подтверждены в Вебмастере.

Попробуйте первым сообщением:

> Какие критичные проблемы сейчас видит диагностика на моём сайте?

[Подключить сервер](#быстрый-старт) · [Посмотреть сценарии](#что-можно-поручить) · [Открыть техническую документацию](#техническая-документация)

---

## Увидеть работу за минуту

> **Вы:** Покажи мои сайты в Вебмастере и кратко оцени их состояние.
>
> **Ассистент:** Показывает сайты, доступные по токену, их ИКС, число страниц в поиске и исключённых страниц, а также количество проблем по степени серьёзности.
>
> **Вы:** Какие критичные проблемы есть у основного сайта и что проверить в первую очередь?
>
> **Ассистент:** Разбирает текущую диагностику Вебмастера, отделяет критичные проблемы от рекомендаций и объясняет, какие из них требуют действий на сайте.
>
> **Вы:** По каким запросам сайт чаще всего показывался за последнюю неделю?
>
> **Ассистент:** Показывает запросы с показами, кликами и средними позициями. При необходимости сравнивает динамику для компьютеров и мобильных устройств.

## Содержание

- [Быстрый старт](#быстрый-старт)
- [Что можно поручить](#что-можно-поручить)
- [Как это работает](#как-это-работает)
- [Что может изменить данные](#что-может-изменить-данные)
- [Подключение и настройка](#подключение-и-настройка)
- [Данные и телеметрия](#данные-и-телеметрия)
- [Ограничения](#ограничения)
- [Техническая документация](#техническая-документация)
- [Поддержка](#поддержка)

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

Нужен Node.js 20+. `npx` скачает сервер при первом запуске — отдельно устанавливать пакет не нужно.
Токен заранее получать не нужно: подключение проходит прямо в диалоге.

1. Добавьте сервер в своё AI-приложение. Выберите инструкцию ниже.
2. Напишите: **«Подключи Яндекс Вебмастер»** — ассистент проведёт через вход в Яндекс и проверит, что видит ваши сайты.
3. Задайте первый вопрос, например: **«Какие критичные проблемы сейчас видит диагностика на моём сайте?»**

Для CI и автоматических установок можно задать готовый токен — см. [Подключение и настройка](#подключение-и-настройка).

<details open>
<summary><b>Codex</b></summary>

**Через интерфейс.** Откройте <b>Settings → Plugins → MCP servers</b>, нажмите <b>Add server</b> и укажите:

- имя: <code>yandex-webmaster</code>;
- команда: <code>npx</code>;
- аргументы: <code>-y mcp-yandex-webmaster@latest</code>.

Сохраните сервер. Он появится в списке MCP-серверов Codex.

**Через командную строку.** Вместо интерфейса можно выполнить:

```bash
codex mcp add yandex-webmaster \
  -- npx -y mcp-yandex-webmaster@latest
```

Проверить, что сервер добавлен: `codex mcp list`.

</details>

<details>
<summary><b>Claude Code</b></summary>

```bash
claude mcp add --transport stdio --scope user \
  yandex-webmaster -- npx -y mcp-yandex-webmaster@latest
```

Проверить подключение: `claude mcp list`.

</details>

<details>
<summary><b>Claude Desktop</b></summary>

Откройте <b>Settings → Developer → Edit Config</b> и добавьте в `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "yandex-webmaster": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-webmaster@latest"]
    }
  }
}
```

Если раздела Developer нет, откройте файл вручную: macOS — `~/Library/Application Support/Claude/claude_desktop_config.json`, Windows — `%APPDATA%\Claude\claude_desktop_config.json`. Перезапустите Claude Desktop.

</details>

<details>
<summary><b>Cursor</b></summary>

Откройте `~/.cursor/mcp.json`, чтобы подключить сервер во всех проектах, или `.cursor/mcp.json` в конкретном проекте. Добавьте:

```json
{
  "mcpServers": {
    "yandex-webmaster": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-webmaster@latest"]
    }
  }
}
```

</details>

<details>
<summary><b>VS Code</b></summary>

В палитре команд выполните <b>MCP: Open User Configuration</b>. В открывшемся `mcp.json` добавьте сервер:

```json
{
  "servers": {
    "yandex-webmaster": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yandex-webmaster@latest"]
    }
  }
}
```

После сохранения выполните <b>MCP: List Servers</b> и запустите сервер из списка.

</details>

## Что можно поручить

### Понять состояние сайта в поиске

- «Покажи мои сайты в Вебмастере и их ИКС».
- «Сколько страниц основного сайта находится в поиске и сколько исключено?»
- «Какие критичные и фатальные проблемы есть на сайте?»
- «Какие важные страницы изменили статус индексации?»

### Разобраться с поисковыми запросами

- «По каким запросам сайт чаще всего показывался за последнюю неделю?»
- «Как менялись показы, клики и средняя позиция сайта за последний месяц?»
- «Сравни видимость сайта на мобильных устройствах и компьютерах».

### Проверить обход, sitemap и внешние ссылки

- «Покажи, какие HTTP-ошибки робот Яндекса встречал при обходе сайта».
- «Есть ли ошибки в sitemap и когда робот в последний раз его читал?»
- «Покажи примеры внешних ссылок на сайт».

### Подготовить действие на сайте

- «Проверь, добавлен ли sitemap https://example.com/sitemap.xml, и объясни, что изменится при добавлении».
- «Сколько переобходов осталось на сегодня для сайта и можно ли отправить страницу в очередь?»
- «Как подтвердить права на новый сайт через DNS?»

## Как это работает

Работа начинается со списка сайтов. У каждого есть технический идентификатор `host_id` — сервер подхватывает его из вашего запроса или из переменной `YANDEX_WEBMASTER_HOST_ID`, если она задана.

После подтверждения прав на сайт сервер может собрать в одном диалоге:

- **состояние в поиске** — ИКС, число страниц в поиске и исключённых страниц, текущие проблемы;
- **видимость по запросам** — показы, клики и средние позиции по датам и типам устройств;
- **обход и индексацию** — HTTP-коды при обходе, статус важных страниц, sitemap и очередь на переобход;
- **ссылочный профиль** — примеры страниц, которые ссылаются на ваш сайт.

Если прав на сайт нет, Вебмастер вернёт `HOST_NOT_VERIFIED`. Если сайт ещё не загружен или не проиндексирован, `HOST_NOT_LOADED` и `HOST_NOT_INDEXED` означают, что данных пока нет, а не нулевые показатели.

## Что может изменить данные

Большинство вопросов к серверу только читают данные. Следующие операции меняют состояние в Яндекс Вебмастере:

| Действие | Что происходит | На что обратить внимание |
| --- | --- | --- |
| Добавить сайт | Сайт появляется в списке сайтов аккаунта. | Права на него нужно подтвердить отдельно. |
| Запустить подтверждение прав | Вебмастер начинает проверять DNS-запись, HTML-файл или мета-тег. | Перед запуском нужно разместить код, который выдал Вебмастер. |
| Добавить sitemap | Sitemap передаётся Вебмастеру. | Повторное добавление вернёт сообщение, что файл уже есть. |
| Отправить страницу на переобход | URL попадает в очередь на обход роботом. | Тратится суточная квота сайта; ответ покажет её остаток. |
| Выполнить прямой запрос API | `raw_request` открывает пути API, для которых нет отдельного инструмента. | `POST` тоже может менять данные, а `DELETE` — безвозвратно удалить сайт или sitemap. |

Инструменты, которые меняют состояние, помечены для AI-приложения как действия, а `raw_request` с возможным удалением — как потенциально необратимое. Приложение может запросить подтверждение, но его поведение зависит от конкретного клиента. Для удаления нужна явная просьба.

## Подключение и настройка

Сервер обращается к [Yandex Webmaster API v4](https://yandex.ru/dev/webmaster/) от имени вашего аккаунта Яндекса и видит те же сайты, которые доступны этому аккаунту в веб-интерфейсе Вебмастера.

Для обычного использования токен заранее не нужен:

1. В чате попросите подключить Яндекс Вебмастер.
2. Откройте ссылку на Яндекс OAuth под аккаунтом, которому в Вебмастере видны нужные сайты.
3. Подтвердите доступ и пришлите показанный код ассистенту. Код одноразовый, действует 10 минут и меняется на токен только внутри работающего сервера — перезапускать приложение и править конфигурацию не нужно.

Сервер использует PKCE: код из чата сам по себе нельзя обменять на токен, поэтому пересылать его в чате безопасно. Полученный токен хранится локально в `~/.config/mcp-yandex-webmaster/credentials.json` с правами только для владельца (`0600`). Дальше подключение живёт само: доступ продлевается автоматически и не отваливается через год. Проверить состояние — попросите «покажи статус подключения», отключить — «отключи Вебмастер»; выданный до