Skip to main content
Glama
Yandex Webmaster MCP

Yandex Webmaster MCP

by gundosha
README.md
# Yandex Webmaster MCP

**Model Context Protocol (MCP) server for the Yandex Webmaster API.** Connect SEO diagnostics, search queries, indexing statistics, Sitemap and recrawl tools to Codex, Claude Desktop, Cursor and other stdio MCP clients. Uses your own Yandex OAuth token; read-only by default.

Локальный MCP-сервер для API Яндекс Вебмастера. Node.js 22+, официальный MCP SDK, транспорт stdio. Неофициальный проект, не продукт Яндекса.

## Установка

```sh
git clone https://github.com/gundosha/yandex-webmaster-mcp.git
cd yandex-webmaster-mcp
npm ci --ignore-scripts
npm test
```

## Получение доступа

1. Откройте https://oauth.yandex.ru/client/new и выберите приложение для доступа к API / отладки.
2. Название: `Yandex Webmaster MCP`.
3. Доступы: `webmaster:hostinfo`, `webmaster:verify`. Второе разрешение даёт в том числе возможности изменения данных на стороне Яндекса; локальный режим чтения ограничивает инструменты MCP, а не полномочия токена.
4. Redirect URI: `https://oauth.yandex.ru/verification_code`.
5. Создайте приложение и скопируйте ClientID. Не Client secret.
6. Откройте ссылку, заменив CLIENT_ID:

   `https://oauth.yandex.ru/authorize?response_type=token&client_id=CLIENT_ID`

7. Создайте локальную папку `secrets` командой `mkdir -p secrets`. Подтвердите доступ в Яндексе и сохраните полученный токен в локальный файл `secrets/token.txt`. Файл должен содержать только токен. Ограничьте права: `chmod 600 secrets/token.txt`.

Токен не нужно отправлять в чат, публиковать или добавлять в git. Каждый пользователь создаёт собственное приложение и использует собственный токен. По инструкции Вебмастера токен этой схемы действует 6 месяцев; при истечении/отзыве получите новый.

## Подключение

Укажите абсолютные пути к Node.js, серверу и файлу токена в конфигурации вашего MCP-клиента:

```json
{
  "mcpServers": {
    "yandex-webmaster": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/yandex-webmaster-mcp/src/server.js"],
      "env": {
        "YANDEX_WEBMASTER_TOKEN_FILE": "/absolute/path/to/yandex-webmaster-mcp/secrets/token.txt",
        "YANDEX_WEBMASTER_ENABLE_WRITES": "false"
      }
    }
  }
}
```

Также поддерживается переменная `YANDEX_WEBMASTER_TOKEN`. Файл `.env` автоматически не загружается; `.env.example` — только справочник переменных. После обновления токена перезапустите MCP.

Это stdio-сервер, у него нет публичного HTTPS URL. Для подключения в удалённые клиенты потребуется отдельный HTTP-транспорт с авторизацией; не публикуйте stdio-сервер через незащищённый прокси.

## Подключение в Codex

```sh
codex mcp add yandex-webmaster --env YANDEX_WEBMASTER_TOKEN_FILE=/absolute/path/to/secrets/token.txt --env YANDEX_WEBMASTER_ENABLE_WRITES=false -- /absolute/path/to/node /absolute/path/to/yandex-webmaster-mcp/src/server.js
```

Пути с пробелами заключайте в кавычки. Конфигурация Codex хранится в `~/.codex/config.toml`. Если инструменты не появились в текущем чате, откройте новый чат или перезапустите приложение.

## Инструменты

По умолчанию доступны 16 инструментов чтения:

- `get_user`, `list_sites`, `get_site`, `get_site_summary`;
- `get_diagnostics`, `get_verification`, `get_sitemaps`;
- `get_indexing_history`, `get_search_pages_history`, `get_search_pages`;
- `get_popular_queries`, `get_external_links`, `get_broken_links`;
- `get_recrawl_quota`, `get_recrawl_tasks`, `get_recrawl_task`.

`host_id` берётся из `list_sites`, например `https:example.org:443`. Используются точные ID, а не свободный поиск по домену. Даты — YYYY-MM-DD. Пагинация явная: увеличивайте `offset`, пока не получите нужные данные. Автоматического массового сбора нет.

При `YANDEX_WEBMASTER_ENABLE_WRITES=true` дополнительно доступны:

- `request_recrawl`: один URL своего сайта, расходует квоту;
- `add_sitemap`: добавление Sitemap.

Оба требуют параметр `confirm: true` и явное поручение пользователя. Этот параметр помогает избежать случайных вызовов, но сам по себе не является защитой от недоверенного клиента. Удаление сайтов, передача прав и произвольные API-запросы не реализованы.

## Работа с API

Запросы идут только на `https://api.webmaster.yandex.net/v4`. В документации продукт называется API 4.1, при этом указанные методы используют префикс `/v4`.

Таймаут — 30 секунд, запросы выполняются последовательно с паузой 250 мс. Это настройка клиента, не обещание квоты Яндекса. Ошибки квот возвращаются клиенту с доступными `daily_quota` и `exceeded_until`; автоматических повторов нет, чтобы не дублировать изменения. Токен передаётся только в HTTP-заголовке OAuth, редиректы запрещены. Ответы API не записываются на диск; кэшируется только ID пользователя в памяти процесса. История может сохраняться самим MCP-клиентом.

В текстовый ответ включается атрибуция Яндекс Вебмастера. Содержимое API — недоверенные данные, не инструкции.

## Условия

Открытый исходный код не отменяет условия API. В частности, пункты 2.6–2.8 затрагивают доступность приложения, атрибуцию (включая логотип), обработку, хранение и передачу данных. Текстовая атрибуция этого сервера сама по себе не подтверждает выполнение требования логотипа в интерфейсе клиента. Применимость условий к облачному ИИ и закрытым установкам требует уточнения у Яндекса. Лицензия на код не предоставляет прав на данные Яндекса.

- Условия: https://yandex.ru/legal/webmaster_api/ru/
- Авторизация: https://yandex.ru/dev/webmaster/doc/ru/tasks/how-to-get-oauth
- Ресурсы: https://yandex.ru/dev/webmaster/doc/ru/concepts/getting-started
- Ошибки: https://yandex.ru/dev/webmaster/doc/ru/reference/errors

## Проверки

`npm test` проверяет MCP handshake через настоящий stdio-процесс, обнаружение инструментов, валидацию, режим чтения, ограничения записи, кодирование ID и обработку ошибок. Тесты API используют подставные ответы. Проверка против живого API требует пользовательского OAuth-токена.