Установка MCP-сервера YTsaurus

В инструкции описано, как установить пакет ytsaurus-mcp и настроить MCP-сервер YTsaurus для работы с AI-ассистентом. В качестве примера используется Cline в Visual Studio Code. MCP-сервер YTsaurus работает по открытому стандарту и совместим с любыми MCP-клиентами: Cursor, Windsurf, Claude Desktop, Roo Code и другими. Конфигурация для них будет аналогичной.

О возможностях сервера и доступных инструментах читайте в разделе Работа с MCP-сервером.

Пререквизиты

Перед началом работы подготовьте:

• Python 3.10 или новее.
• Токен для доступа к кластеру YTsaurus. Как выпустить токен, читайте в разделе Управление токенами. Обычно токен хранится в файле ~/.yt/token.
• MCP-совместимый AI-ассистент с подключённой LLM-моделью: Cline в Visual Studio Code, Cursor, Claude Desktop. Без подключённой модели ассистент не отвечает, поэтому модель подключается в Шаге 2.

Шаг 1. Установка пакета

Установите пакет ytsaurus-mcp:

pip3 install ytsaurus-mcp

На свежих сборках Python, например на 3.14, установка системным pip3 может завершиться ошибкой при сборке зависимостей. Если это произошло, установите пакет через python3 -m pip:

python3 -m pip install ytsaurus-mcp

Затем найдите абсолютный путь к исполняемому файлу — он понадобится в параметре command конфигурации MCP-клиента. Выполните команду:

which mcp_yt_server

(Get-Command mcp_yt_server).Source

Команда возвращает абсолютный путь к исполняемому файлу, например:

$ which mcp_yt_server

/usr/local/bin/mcp_yt_server

Запишите полученный путь — он пригодится в Шаге 2.

Убедитесь, что сервер установлен корректно. Для этого выведите список доступных инструментов — команда напечатает их и завершится:

$ mcp_yt_server --show-tools

Tools:
- list_dir (ListDir)
- find (Search)
- get_attributes_account (GetAttributes)
- get_attributes_account_limits_disk (GetAttributes)
- get_attributes_bundle (GetAttributes)
- get_attributes_pool (GetAttributes)
- check_is_paths_exist (CheckIsPathsExists)
- common_client_get_table_schema (CommonCypress)
- common_client_read_table (CommonCypress)
- common_client_sample_static_table (CommonCypress)
- common_client_infer_table_schema (CommonCypress)
- common_client_whoami (CommonCypress)
- check_permission (CheckPermissions)
- get_account_property (AccountProperty)
- get_proxy (GetProxy)

Сервер не привязывается к конкретному кластеру: имя кластера передаётся в каждом запросе к инструменту. Как задать кластер в запросе к ассистенту — в Шаге 3.

Шаг 2. Настройка MCP-клиента на примере Cline

Настройка состоит из трёх частей. Сначала устанавливается расширение Cline, затем подключается LLM-модель и только потом настраивается сам MCP-сервер. Без LLM-модели ассистент не отвечает и не вызывает инструменты.

2.1. Установка расширения Cline

1. Установите расширение Cline из маркетплейса Visual Studio Code или из панели расширений VS Code.

2. Перезапустите Visual Studio Code.

2.2. Подключение LLM-модели

Чтобы подключить LLM-модель:

1. На боковой панели Visual Studio Code откройте плагин Cline.

2. Нажмите значок шестерёнки Settings.

3. Укажите API-ключ провайдера и выберите модель для планирования и действий.

4. Нажмите Done.

2.3. Добавление MCP-сервера

Чтобы добавить MCP-сервер:

1. На боковой панели Visual Studio Code откройте плагин Cline.

2. Нажмите значок гаечного ключа — откроется вкладка Customize.

3. В открывшемся окне выберите MCP — здесь задаются настройки MCP-серверов.

4. Нажмите Edit Configuration — откроется файл cline_mcp_settings.json. Добавьте конфигурацию. Подставьте абсолютные пути, полученные в Шаге 1:

   • command — абсолютный путь к исполняемому файлу mcp_yt_server из вывода which mcp_yt_server;
   • --yt-token-file — абсолютный путь к файлу токена. Аргумент необязателен, если токен задан в переменной окружения MCP_YT_TOKEN. Подробнее читайте в разделе Продвинутые настройки.
   Пример конфигурации

   {
     "mcpServers": {
       "local-yt-server-python": {
         "env": {},
         "args": [
           "--log-file=/tmp/out.log",
           "--log-level=DEBUG",
           "--yt-token-file=/Users/ivan/.yt/token"
         ],
         "command": "/usr/local/bin/mcp_yt_server",
         "disabled": false,
         "alwaysAllow": [],
         "type": "stdio"
       }
     }
   }
   

   Меняйте только command и --yt-token-file — остальные поля оставьте как есть. Аргументы --log-file и --log-level опциональны: они включают запись отладочного лога и нужны только для диагностики проблем. О дополнительных возможностях сервера читайте в разделе Продвинутые настройки.

5. Сохраните файл и нажмите Done.

6. Убедитесь, что сервер появился в списке серверов на вкладке Installed и горит зелёным индикатором — это означает успешный запуск. Если индикатор красный, проверьте пути к исполняемому файлу и токену в конфигурации.

Шаг 3. Проверка работы

Убедитесь, что после добавления в Шаге 2 сервер в списке Installed горит зелёным индикатором. Затем напишите ассистенту простой запрос, например:

«Покажи содержимое директории //home на кластере <имя-кластера>»

Кластер — это параметр каждого вызова инструмента, а не глобальная настройка сервера. Поэтому имя кластера указывается в тексте запроса к ассистенту, а не в конфигурации mcpServers.

Если ассистент вернул список объектов — сервер работает корректно. Если появилась ошибка авторизации, проверьте путь к файлу токена в конфигурации и убедитесь, что токен действует. Подробнее читайте в разделе Управление токенами.

Полный список доступных инструментов и примеры запросов смотрите в разделе Методы MCP-сервера.

Продвинутые настройки

Эти параметры не нужны для базовой работы — настраивайте их по необходимости.

Указание токена через переменную окружения

Вместо файла токена --yt-token-file токен можно передать через переменную окружения MCP_YT_TOKEN в поле env конфигурации:

"env": { "MCP_YT_TOKEN": "<токен>" }

Источники токена сервер проверяет в следующем порядке:

1. Переменная окружения MCP_YT_TOKEN — наивысший приоритет.
2. Аргумент --yt-token-file.
3. Значение по умолчанию клиента yt — файл ~/.yt/token или переменная YT_TOKEN.

Переменную MCP_YT_TOKEN читает сам MCP-сервер. Переменная YT_TOKEN относится к библиотеке ytsaurus-client и используется только как запасной вариант, когда ни MCP_YT_TOKEN, ни --yt-token-file не заданы.

Выбор группы инструментов

По умолчанию включены все инструменты из трёх групп: common, account и admin. Чтобы включить только определённые группы, укажите соответствующие флаги в args:

Если указан хотя бы один флаг --tools-*, включаются только выбранные группы. Если не указан ни один флаг — включаются все три группы.

Транспорт

По умолчанию сервер работает по транспорту stdio — этот режим используется в Cline и большинстве локальных MCP-клиентов. Для сетевого доступа используйте sse:

"args": ["--server-transport=sse"]

Логирование

Для диагностики проблем включите запись отладочного лога:

Пример:

"args": [
  "--log-file=/tmp/mcp_yt_server.log",
  "--log-level=DEBUG"
]