Как установить uvx на Windows, macOS и Linux: пошаговая инструкция

Открываете инструкцию к MCP-серверу, а в конфиге команда uvx и никаких пояснений, откуда её взять. Если сервер написан на Python, скорее всего, он запускается именно так. Разберёмся, что такое uvx, почему через него поднимается столько MCP-серверов и как поставить его на Windows, macOS и Linux.

Зачем вообще нужен uvx

Значительная часть MCP-серверов написана на Python. Чтобы клиент (Claude Desktop, Cursor, VS Code) запустил такой сервер, пакет нужно скачать и выполнить в подходящем окружении. За это отвечает uvx. В конфиге это выглядит так:

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

Клиент читает конфиг и выполняет uvx mcp-server-fetch. uvx скачивает пакет во временное окружение, запускает его и ничего не оставляет в системе. По сути это тот же npx из мира Node.js, только для Python. Удобно: не нужно вручную создавать виртуальное окружение под каждый сервер и следить за зависимостями, всё поднимается на лету.

Так что без uvx инструкции по установке Python-серверов просто не сработают. А ставить его отдельно и не придётся, и вот почему.

Что такое uv и uvx и откуда они берутся

uvx живёт внутри uv, быстрого менеджера пакетов и виртуальных окружений для Python, написанного на Rust. Ставите uv, и uvx приезжает вместе с ним, отдельной установки у него нет.

И тут приятная особенность: uv это самостоятельный бинарник. Ему даже не нужен заранее установленный Python, он сам скачает нужную версию, когда та понадобится. То есть ставим одну утилиту, а на выходе получаем и менеджер пакетов, и uvx, и Python при необходимости.

Отсюда главное правило: чтобы получить uvx, ставим uv. Дальше пройдёмся по установке для каждой системы по очереди.

Установка на Windows

Откройте PowerShell и выполните официальный скрипт установки:

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

Если пользуетесь пакетным менеджером winget, можно и через него:

winget install astral-sh.uv

После установки закройте терминал (PowerShell или cmd) и откройте заново, открытые окна про новый PATH ещё не знают. Потом проверьте, что всё встало:

uv --version
uvx --version

Обе команды должны выдать номер версии. Выдали, значит uvx готов к работе.

Установка на macOS

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

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

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

brew install uv

Проверяем результат:

uv --version
uvx --version

Обе команды показали версию, всё на месте. А если терминал отвечает command not found, закройте его и откройте заново, чтобы подтянулись свежие пути.

Установка на Linux

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

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

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

uv --version
uvx --version

Версии вывелись, готово.

Если предпочитаете ставить всё из системного менеджера, uv есть и в некоторых дистрибутивах, но там частенько лежит устаревшая версия, которую потом неудобно обновлять. Для MCP-серверов с официальным скриптом обычно спокойнее.

Проверка и что дальше

Проверка на любой системе одна и та же:

uv --version
uvx --version

Обе команды отвечают номером версии, значит uv и uvx на месте, и можно возвращаться к настройке MCP-сервера. Только обязательно полностью перезапустите клиент (Claude Desktop, Cursor, VS Code): не свернуть, а закрыть и открыть заново. Иначе он подтянет старое окружение и uvx не увидит.

Клиент не видит uvx, хотя он установлен: проблема с PATH

Частая ситуация: в терминале uvx --version честно показывает версию, а клиент всё равно падает с uvx is not recognized или command not found. Значит, установка тут ни при чём, дело в PATH.

PATH это переменная окружения со списком папок, где система ищет исполняемые файлы. Набрали uvx, и система идёт по списку папка за папкой, пока не наткнётся на нужный файл. Терминал при запуске подгружает ваши настройки (.zshrc, .bashrc на macOS и Linux, системный PATH на Windows), и папка ~/.local/bin, куда установщик кладёт uvx, туда попадает. Поэтому в терминале всё работает. А вот Claude Desktop, Cursor и прочие приложения с графическим интерфейсом стартуют в обход этих настроек, с урезанным PATH, где про эту папку ничего не сказано. Отсюда и command not found при живом uvx в соседнем окне.

Лечится в лоб: не заставляйте клиент искать uvx по имени, пропишите в конфиге полный путь до файла. Узнать путь:

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

Дальше в конфиге меняете короткое имя на этот путь:

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

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

Если после этого ошибка не ушла, частные случаи подробно разобраны в статье Ошибки uvx при запуске MCP-сервера.