Yandex Ultimate MCP

🇷🇺 Основной язык — русский. English quick start is below.

Yandex Ultimate MCP — неофициальный “ультимативный” MCP-gateway для Яндекс-экосистемы. Он не копирует код чужих серверов: запускает лучшие найденные open-source MCP как дочерние процессы, собирает их tools в один интерфейс, добавляет doctor, auth-wizard, статусы, нормальные ENV-подсказки и безопасные notices по лицензиям.

🚀 Автовход и получение ключей/токенов

Самый быстрый сценарий:

cd /Users/vlad/yandex-ultimate-mcp
npm run auth
npm run doctor
npm run start

Wizard теперь работает как маршрут, а не как “держи ссылки”:

1. Поднимает локальный callback: http://127.0.0.1:17893/callback.

2. Сам открывает страницу создания Yandex OAuth app.

3. Показывает, что вставить в OAuth app:

   • name: Yandex Ultimate MCP

   • type: Для доступа к API или отладки

   • manual redirect URI: https://oauth.yandex.ru/verification_code

   • optional auto-capture redirect URI: http://127.0.0.1:17893/callback

   • permissions: metrika:read/write, direct:api, Webmaster scopes, tracker:read/write.

4. Ты вставляешь ClientID в терминал.

5. Wizard спрашивает только про optional localhost Redirect URI:

   • если да — ловит access_token сам через localhost;

   • если нет — использует официальный ручной flow: ты копируешь URL вида https://oauth.yandex.ru/verification_code#access_token=....

6. Если видишь 400 redirect_uri не совпадает, значит в OAuth app нет выбранного Redirect URI: используй ручной режим или добавь точный localhost URI.

7. Token раскладывается в:

   • YANDEX_TOKEN

   • YANDEX_METRIKA_TOKEN

   • YANDEX_DIRECT_TOKEN

   • YANDEX_WEBMASTER_TOKEN / YANDEX_WEBMASTER_OAUTH_TOKEN

   • YANDEX_TRACKER_TOKEN

8. Потом wizard сам открывает/подсказывает страницы для Direct, Cloud/Search и Maps keys.

Если нужен именно Helium с твоими cookies:

ULTIMATE_BROWSER_APP=Helium npm run auth

Важно: YANDEX_CLIENT_LOGIN — это не токен. Это логин клиента/аккаунта в Yandex Direct. Если Direct не нужен — пропусти.

Webmaster обычно использует тот же OAuth token. Если в OAuth app нет Webmaster permissions или API-доступ ограничен аккаунтом, doctor покажет, что модуль не включился.

Отдельно добираются:

• YANDEX_TRACKER_ORG_ID — id организации Tracker;

• YC_FOLDER_ID / YC_OAUTH_TOKEN — Yandex Cloud; если установлен yc, wizard сам подставляет yc config list;

• YANDEX_SEARCH_API_KEY / YANDEX_FOLDER_ID — Yandex Cloud Search API для текущего MCP;

• Поиск для сайта — отдельный маршрут: ключ в developer.tech.yandex.ru + подключение к поиску на site.yandex.ru;

• YANDEX_MAPS_API_KEY — Maps.

⚠️ Если токен случайно попал в чат, логи или скриншот — лучше отозвать его и выпустить новый.

Если auto-open браузера не нужен:

ULTIMATE_NO_OPEN=1 npm run auth

Что внутри

Плюшки:

• один MCP endpoint вместо пачки разрозненных servers;

• авто-скрытие модулей без токенов, понятный ultimate_status;

• ultimate_auth_help, yandex-ultimate auth, .env.example и подробный docs/AUTH.md;

• collision-safe tool names: если имена пересеклись, gateway покажет module__tool;

• ULTIMATE_PREFIX_TOOLS=1, если хочется всегда явно видеть источник tool;

• safe-by-default: секреты не логируются, .env.local в .gitignore;

• MIT проект + THIRD_PARTY_NOTICES.md для upstream MCP.

Установка

npm install -g yandex-ultimate-mcp
# или без установки:
npx yandex-ultimate-mcp@latest doctor

Для разработки из репозитория:

git clone https://github.com/lemonchikHere/yandex-ultimate-mcp.git
cd yandex-ultimate-mcp
npm install
cp .env.example .env.local
npm run build
npm run doctor

Подключение к MCP-клиенту

Codex / Claude Desktop / Cursor-style stdio

{
  "mcpServers": {
    "yandex-ultimate": {
      "command": "npx",
      "args": ["-y", "yandex-ultimate-mcp@latest", "serve"],
      "env": {
        "YANDEX_TOKEN": "...",
        "YANDEX_CLIENT_LOGIN": "...",
        "YANDEX_WEBMASTER_TOKEN": "...",
        "YANDEX_WEBMASTER_OAUTH_TOKEN": "...",
        "YANDEX_TRACKER_TOKEN": "...",
        "YANDEX_TRACKER_ORG_ID": "...",
        "YC_OAUTH_TOKEN": "...",
        "YC_FOLDER_ID": "...",
        "YANDEX_SEARCH_API_KEY": "...",
        "YANDEX_FOLDER_ID": "...",
        "YANDEX_MAPS_API_KEY": "..."
      }
    }
  }
}

Локально из checkout:

{
  "mcpServers": {
    "yandex-ultimate-local": {
      "command": "node",
      "args": ["/ABS/PATH/yandex-ultimate-mcp/dist/src/cli.js", "serve"],
      "env": { "YANDEX_TOKEN": "..." }
    }
  }
}

Быстрый auth

yandex-ultimate auth
# или
npx yandex-ultimate-mcp@latest auth

Wizard сам открывает страницы, использует официальный ручной OAuth flow или optional localhost auto-capture, вытаскивает access_token, подхватывает yc config list и пишет .env.local без дублей. Подробности: docs/AUTH.md.

Webmaster token / WEBMASTER_TOKEN

Для Яндекс.Вебмастера OAuth app лучше заводить так:

1. Открой создание OAuth-приложения: https://oauth.yandex.ru/client/new

2. Название любое, например Yandex Ultimate MCP.

3. Тип приложения: Для доступа к API или отладки.

4. Redirect URI для ручного режима: https://oauth.yandex.ru/verification_code; localhost URI из wizard добавляй только если нужен auto-capture.

5. В поле Доступ к данным напиши webmaster.

6. В появившемся списке выбери все 3 элемента Webmaster.

7. Создай приложение, скопируй ClientID, запусти npm run auth и получи новый token.

8. Wizard сохранит его как YANDEX_WEBMASTER_TOKEN и YANDEX_WEBMASTER_OAUTH_TOKEN.

Если get-user возвращает 403 ACCESS_FORBIDDEN и application scopes: [], значит token выпущен без Webmaster scopes — нужно перевыпустить token после выбора этих доступов.

Live Webmaster check

npm run doctor теперь не только проверяет наличие env, но и делает read-only запрос:

GET https://api.webmaster.yandex.net/v4/user
Authorization: OAuth <token>

Если видишь 403 ACCESS_FORBIDDEN / application scopes: [], токен выпущен без Webmaster scopes — перевыпусти его, выбрав все 3 доступа webmaster.

Yandex Search vs Поиск для сайта

Внутри gateway сейчас подключен yandex-search-mcp — это Yandex Cloud Search API. Для него нужны:

YANDEX_SEARCH_API_KEY=...
YANDEX_FOLDER_ID=...

Документация, которую ты нашел — это Яндекс.Поиск для сайта: https://yandex.ru/dev/site/doc/ru/concepts/access

Там другой путь:

1. Получить ключ в Кабинете разработчика: https://developer.tech.yandex.ru/services/

2. Выбрать сервис API Яндекс.Поиска для сайта.

3. Открыть Мои поиски: https://site.yandex.ru/

4. В выбранном поиске на странице Выдача в JSON вставить API-ключ.

5. Подождать до часа, пока изменения вступят в силу.

Важно: один ключ Поиска для сайта подключается только к одному поиску.

Управление модулями

# только Direct/Metrika/Wordstat + Webmaster
ULTIMATE_ENABLE_MODULES=stegyan,webmaster yandex-ultimate-mcp serve

# отключить справочник документации
ULTIMATE_DISABLE_MODULES=cloud_docs yandex-ultimate-mcp serve

# всегда namespace-prefix
ULTIMATE_PREFIX_TOOLS=1 yandex-ultimate-mcp serve

Management tools внутри MCP:

• ultimate_status — что настроено, что включено, какие ошибки у child MCP;

• ultimate_modules — каталог модулей/источников/лицензий;

• ultimate_auth_help — auth hints;

• ultimate_refresh_tools — очистить cache tools.

Почему gateway, а не “скопировать всё в один server”?

Так лучше юридически и технически:

• upstream MCP остаются самостоятельными пакетами со своими лицензиями;

• обновления подтягиваются через npx ...@latest;

• меньше риска сломать чужую реализацию API;

• можно быстро заменить слабый модуль на более полный.

Мы специально не тащим код из пакетов с ограничительными/неподходящими лицензиями. Список источников и исключений — в docs/SOURCES.md.

Разработка

npm install
npm run build
npm run smoke
npm run audit
npm run modules

Smoke test запускает только management tools (ULTIMATE_DISABLE_CHILDREN=1), чтобы CI не требовал реальных токенов.

English quick start

Yandex Ultimate MCP is an unofficial MCP gateway for the Yandex ecosystem. It aggregates existing open-source Yandex MCP servers behind one stdio endpoint and adds auth helpers, diagnostics, module controls and license notices.

npm install -g yandex-ultimate-mcp
yandex-ultimate-mcp doctor
yandex-ultimate-mcp auth
yandex-ultimate-mcp serve

Read docs/AUTH.md for tokens/API keys and THIRD_PARTY_NOTICES.md for upstream modules.

License

MIT for this gateway. Upstream MCP packages keep their own licenses and are executed as separate child processes.