Каталог MCP
Блог
Ошибки uvx и uv при запуске MCP-сервера и как их починить

Ошибки uvx и uv при запуске MCP-сервера и как их починить

4 июля 20263 мин чтенияВалентин Попов

MCP-сервер отказывается стартовать, а в логах мелькает что-то про uvx. История почти всегда одна: сервер запускается через uvx (или uv), а этой утилиты на компьютере просто нет. Чинится за пару минут. Ниже разберём, что это за инструмент, как его ошибки выглядят на разных системах и как всё поправить.

Что такое uv и uvx

uv это быстрый менеджер пакетов и виртуальных окружений для Python, написанный на Rust. uvx живёт внутри него и делает ровно одну вещь: скачивает Python-пакет во временное окружение и тут же запускает его, ничего не оставляя в системе. По сути тот же npx из мира Node.js, только для Python.

Многие MCP-серверы написаны на Python, и в инструкции по установке у них стоит именно uvx. В конфиге это выглядит так:

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}

Когда клиент (Claude Desktop, Cursor, VS Code) стартует, он читает этот конфиг и пытается выполнить uvx mcp-server-fetch. Нет uvx в системе, нет и сервера, а вы ловите ошибку в логах.

Как выглядят ошибки на разных платформах

Текст зависит от операционной системы и клиента, но смысл везде один: команда не найдена.

Windows (cmd / PowerShell):

[error] 'uvx' is not recognized as an internal or external command,
operable program or batch file.

uvx : The term 'uvx' is not recognized as the name of a cmdlet, function,
script file, or operable program.

macOS (zsh / bash):

zsh: command not found: uvx

env: uvx: No such file or directory

Linux (bash):

bash: uvx: command not found

В логах самого клиента это часто прячется за сообщением вроде spawn uvx ENOENT или MCP server exited with code 1. Звучит страшнее, но корень тот же: исполняемого файла uvx нет в PATH, и система не знает, где его искать.

Та же история с uv, если сервер прописан через него:

'uv' is not recognized as an internal or external command
zsh: command not found: uv
bash: uv: command not found

Как установить uv и uvx

uvx ставится не отдельно, а вместе с uv, одной командой. После этого ошибка уйдёт и сервер заведётся.

Windows

Откройте PowerShell и выполните:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS

Проще всего через официальный скрипт установки:

curl -LsSf https://astral.sh/uv/install.sh | sh

Или через Homebrew, если он у вас уже стоит:

brew install uv

Linux

Тот же официальный скрипт, что и на macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

Скрипт кладёт uv и uvx в ~/.local/bin и дописывает эту папку в PATH.

После установки

Перезапустите терминал. Установщик правит PATH, но уже открытые окна об этом не знают. Закройте их и откройте заново, иначе uvx по-прежнему «не найдётся».
Проверьте, что всё встало:

uvx --version

Вывелся номер версии, значит порядок.

Полностью перезапустите MCP-клиент. Claude Desktop, Cursor или VS Code нужно именно закрыть и открыть заново (а не просто свернуть), чтобы приложение подхватило обновлённый PATH.

После этого сервер, который падал с uvx not found, стартует как ни в чём не бывало.

Если ошибка осталась

Бывает и так: uvx установлен, в терминале работает, а клиент всё равно его не видит. Обычно виноват один из двух моментов.

Клиент не видит PATH. PATH это переменная в macOS и Linux, где перечислены пути к исполняемым файлам. Приложения с графическим интерфейсом запускаются в обход вашего терминального окружения и об этой переменной могут просто не знать. Лечится в лоб: пропишите в конфиге полный путь к uvx вместо короткого имени. Узнать путь можно так:

which uvx          # macOS / Linux
where.exe uvx      # Windows

Дальше в конфиге меняете "command": "uvx" на полный путь:

"command": "/Users/me/.local/bin/uvx"

На Windows путь будет вида "C:\\Users\\me\\.local\\bin\\uvx.exe" (обратные слэши в JSON обязательно удваиваются).

Перезапустили не то или не до конца. Самая обидная причина. Проверьте, что перезагрузили и терминал, и сам клиент целиком, а не одно из двух. На словах мелочь, но именно на ней спотыкается половина случаев.