Яндекс Вебмастер MCP: подключение и диагностика сайта

Яндекс Вебмастер MCP позволяет спросить агента, какие страницы сайта есть в поиске, какие проблемы обнаружил Яндекс и по каким запросам сайт получает показы. Я написал этот open-source сервер на Go для своего SEO Agent. Он получает отчёты через API Вебмастера и возвращает данные, на которых можно проверить вывод агента.

В этой инструкции пройдём от демо без аккаунта до подключения Codex, Claude Code, Cursor или VS Code и первого отчёта. Сервер независимый, не является продуктом Яндекса и разворачивается на твоём компьютере или сервере. Для запуска через Docker нужен Docker Compose; подписка на AI-клиент и хостинг оплачиваются отдельно, если они тебе нужны.

1. Запустить демо без OAuth-токена

В терминале выполни команды по порядку. Сборка использует текущий исходный код репозитория.

git clone https://github.com/tenqz/webmaster-mcp.git
cd webmaster-mcp
docker compose -f compose.demo.yml up -d --build
docker compose -f compose.demo.yml exec mcp /mcp-server --smoke http://127.0.0.1:8080/mcp

Демо возвращает явно обозначенные синтетические данные и не обращается к Яндексу. Успешный smoke проверяет MCP и представительный набор инструментов. Он ещё не подтверждает доступ к твоему сайту.

• Адрес MCP на этой машине: http://localhost:8080/mcp.
• Заголовок для клиента: Authorization: Bearer demo-token.
• Демо-сайт: https:example.invalid:443.

Если порт занят, выбери свободный: HTTP_PORT=18080 docker compose -f compose.demo.yml up -d --build. В клиенте тогда нужен порт 18080; команда smoke внутри контейнера по-прежнему использует 8080.

2. Подключить AI-клиент

Выбери один клиент. Примеры ниже подключаются к локальному демо. Для рабочего сервера замени адрес и используй его MCP_AUTH_TOKEN. OAuth-токен Яндекса остаётся на стороне MCP-сервера. Если клиент работает на другой машине или в облаке, его localhost не указывает на твой компьютер: потребуется доступный ему HTTPS-адрес.

Codex

Добавь отдельную секцию в ~/.codex/config.toml, сохранив остальные настройки:

[mcp_servers.yandex_webmaster]
url = "http://localhost:8080/mcp"
bearer_token_env_var = "MCP_AUTH_TOKEN"

Для демо запусти Codex CLI из терминала с переменной:

export MCP_AUTH_TOKEN=demo-token
codex

В диалоге /mcp покажет подключённые серверы. Приложение или расширение тоже должно получить переменную в своём окружении: экспорт в отдельном терминале не меняет окружение уже работающего приложения. Формат конфигурации описан в официальной документации Codex.

Claude Code

Для локального демо выполни в Bash:

export MCP_AUTH_TOKEN=demo-token
claude mcp add-json --scope user yandex-webmaster '{"type":"http","url":"http://localhost:8080/mcp","headers":{"Authorization":"Bearer ${MCP_AUTH_TOKEN}"}}'
claude

Одинарные кавычки вокруг JSON сохраняют ссылку на переменную: Claude Code получает её из своего окружения. В рабочей настройке используй свой MCP-токен. Проверь соединение через /mcp. Это настройка Claude Code; конфиг не предназначен для вставки в Claude Desktop. См. документацию Claude Code.

Cursor

В личный ~/.cursor/mcp.json добавь сервер, объединив его с уже существующим mcpServers:

{
  "mcpServers": {
    "yandex-webmaster": {
      "url": "http://localhost:8080/mcp",
      "headers": {"Authorization": "Bearer ${env:MCP_AUTH_TOKEN}"}
    }
  }
}

Cursor должен унаследовать MCP_AUTH_TOKEN=demo-token при запуске. Включи сервер в настройках MCP. Для VS Code готовый конфиг с приватным запросом токена находится в инструкции подключения. Там же описаны различия клиентов и ограничения Claude Desktop.

Первый запрос в выбранном клиенте: «Вызови list_hosts через Webmaster MCP и покажи точные идентификаторы доступных сайтов». Демо должно вернуть https:example.invalid:443. Это проверяет весь путь от клиента до инструмента.

3. Подключить свой аккаунт Яндекса

Для реальных отчётов сайт должен быть добавлен и подтверждён в Вебмастере под нужным аккаунтом. Сначала останови демо и создай локальный файл настроек:

docker compose -f compose.demo.yml down
test -f .env || cp .env.example .env

Если для демо ты выбрал другой порт, добавь HTTP_PORT=18080 в .env, подставив свой номер. В настройках клиента используй тот же порт. Существующий .env команда выше сохраняет.

1. Открой регистрацию OAuth-приложения Яндекса. Подробные поля и права приведены в пошаговой инструкции получения доступа.
2. Получи пользовательский OAuth-токен с правом webmaster:hostinfo и запиши его в YANDEX_WEBMASTER_TOKEN внутри .env.
3. Сгенерируй отдельный секрет командой openssl rand -hex 32 и запиши его в MCP_AUTH_TOKEN. Этот секрет нужен AI-клиенту.
4. Для автоматического сбора установи MCP_READ_ONLY=true. Запусти рабочий сервер и проверь доступ:

docker compose up -d --build
docker compose exec mcp /mcp-server --smoke http://127.0.0.1:8080/mcp

Теперь замени демо-токен в окружении клиента на рабочий MCP-токен и переподключись. Встроенного браузерного OAuth-входа у сервера нет. Для смонтированных секретов поддерживаются YANDEX_WEBMASTER_TOKEN_FILE и MCP_AUTH_TOKEN_FILE; не задавай одновременно файл и соответствующее значение. Настройка удалённого сервера описана в руководстве по HTTPS и Docker.

4. Получить первый проверяемый отчёт

Вызови list_hosts и предложи выбрать сайт. Используй host_id ровно из ответа. Получи get_summary и get_diagnostics. Покажи исходные показатели, проверки PRESENT и отдельно UNDEFINED. Укажи время запроса и даты данных, если источник их вернул. Не отправляй страницы на переобход.

https:example.com:443 и http:example.com:80 — разные хосты. Не составляй host_id из домена самостоятельно. В диагностике ABSENT означает отсутствие конкретной проблемы, а UNDEFINED не означает успешную проверку. Время запроса также не равно дате обновления показателей у Яндекса.

Реальный пример: что Вебмастер вернул для opatsay.com

12 сентября 2026 года в 14:29:23 UTC я прочитал отчёты своего сайта через работающий Webmaster MCP. list_hosts вернул подтверждённый хост https:opatsay.com:443. Далее я вызвал get_summary, get_diagnostics и get_insearch_history. Это данные реального аккаунта, отдельно от синтетического демо выше.

Запрос к get_summary использовал {"host_id":"https:opatsay.com:443"}. Вот полученный объект structuredContent:

{
  "excluded_pages_count": 4,
  "searchable_pages_count": 50,
  "site_problems": {},
  "sqi": 0
}

Сводка показала 50 страниц в поиске и 4 исключённые. Диагностика вернула 32 проверки ABSENT, ни одной PRESENT и одну UNDEFINED — NOT_MOBILE_FRIENDLY. Пустой объект site_problems в сводке поэтому не заменяет разбор отдельной диагностики.

Для истории я передал date_from=2026-08-29 и date_to=2026-09-11. Источник вернул только три наблюдения:

{
  "history": [
    {
      "date": "2026-09-07T10:00:02.566+03:00",
      "value": 19
    },
    {
      "date": "2026-09-09T10:00:06.709+03:00",
      "value": 48
    },
    {
      "date": "2026-09-10T10:10:02.445+03:00",
      "value": 50
    }
  ]
}

Количество страниц в поиске изменилось с 19 до 50 между этими наблюдениями. Это не показатель трафика и не доказательство эффекта новых статей или редизайна. Три точки также нельзя выдавать за полный ежедневный ряд.

Следующее действие: проверить причины исключения четырёх страниц в Вебмастере, а мобильную верстку оценить отдельно. UNDEFINED не доказывает ни ошибку адаптивности, ни успешную проверку. Массово отправлять URL на переобход по этой сводке оснований нет.

14:29:23 UTC — время моего запроса. Даты наблюдений в истории вернул Яндекс. Сервер не сообщил единую дату актуальности сводки, поэтому я её не придумываю. Как этот сценарий связан с архитектурой сервера.

Пять задач для следующего диалога

В каждом запросе укажи выбранный сайт и требуемый период. Агент должен показывать фактически доступные даты и ограничения выборки.

Страницы в поиске

Получи get_insearch_history и get_insearch_samples для выбранного host_id. Покажи динамику количества страниц и несколько URL из выборки. Не выдавай выборку за полный список индекса; отдельно укажи доступный период.

Поисковые запросы

Получи get_popular_queries. Покажи запросы, показы, клики и доступные позиции. Если обе метрики есть и показы больше нуля, рассчитай CTR. Предложи, какие запросы стоит изучить подробнее; не подменяй отсутствующие данные нулями.

Обход роботом

Сравни get_indexing_history и get_insearch_history. Раздели скачивание страниц роботом и присутствие страниц в поиске. Укажи, какие изменения видны в данных, а какие причины пока не подтверждены.

Sitemap

Получи get_sitemaps. Покажи известные карты сайта и доступные сведения об обработке. Если данных нет, так и напиши. Не считай наличие sitemap доказательством индексации всех URL.

Переобход без отправки

Получи get_recrawl_quota и get_recrawl_queue. Покажи остаток квоты и доступные задания. Ничего не отправляй. Если исход предыдущей отправки неизвестен, объясни, что удалось установить из очереди.

Когда агент может отправить URL на переобход

submit_recrawl — единственный инструмент записи. Он расходует дневную квоту и не обещает немедленного появления страницы в поиске. При MCP_READ_ONLY=true доступны 33 инструмента, переобход скрыт из каталога и прямой вызов тоже запрещён. Обычный режим предоставляет 34 инструмента.

Отправка никогда не повторяется автоматически. Если запрос уже мог попасть в Яндекс, outcome_unknown означает неизвестный исход, а не подтверждённый отказ. Сначала проверь очередь, затем отдельно решай, нужна ли новая отправка.

Если подключение или отчёт не работают

Сервер отвечает 401

Если ошибка приходит от MCP endpoint, проверь адрес, заголовок Authorization и MCP_AUTH_TOKEN. Для демо нужен demo-token. Если истёк именно токен Яндекса, обнови YANDEX_WEBMASTER_TOKEN на сервере и пересоздай контейнер.

Яндекс возвращает 403 или список сайтов пуст

Сначала прочитай код ошибки инструмента: unauthenticated может означать недействительный OAuth-токен даже при HTTP 403 — такой токен нужно заменить. При permission_denied проверь аккаунт, права OAuth и подтверждение сайта. Используй хост из list_hosts, включая схему и порт. Новый токен сам по себе не выдаёт доступ к чужому или неподтверждённому сайту.

Запросы или история пустые

Проверь сайт, период и наличие данных в Вебмастере. Пустой отчёт может быть корректным ответом. Он не доказывает нулевой трафик, отсутствие индекса или исправность всех проверок.

Почему клиент не видит переобход

Проверь MCP_READ_ONLY. Для планового сборщика отсутствие этого инструмента — ожидаемое поведение.

Нужен ли отдельный сервер

Для локального клиента достаточно запустить MCP на том же компьютере. Для постоянной работы SEO Agent нужен работающий экземпляр сервиса. Удалённый клиент подключается к доступному ему HTTPS-адресу; этот проект не предоставляет общий публичный сервис с твоими данными.

Дополнительные ошибки, квоты и тайм-ауты разобраны в README.

Как я использую MCP в SEO Agent

Webmaster MCP получает отчёты. SEO Agent сохраняет наблюдения и даты в PostgreSQL, а SEO Version Control хранит изменения страниц. Рядом работают GSC MCP и ahref. Такая история позволяет сопоставлять события, но сама по себе не доказывает, что конкретная правка вызвала изменение поискового трафика.

В инженерном кейсе Webmaster MCP я показываю схему системы, ограничения запросов и тесты запрета записи и неопределённого исхода переобхода. Там можно проверить решения по исходному коду.

Исходный код и установка · Настройки клиентов · Что такое MCP