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-токена.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues