---
title: Ошибки uvx и uv при запуске MCP-сервера и как их починить
description: Почему MCP-сервер падает с ошибками вроде «uvx is not recognized» или «uvx ENOENT» на Windows, macOS и Linux. Показываем, как исправить проблемы с uv/uvx на каждой платформе.
createdAt: 2026-07-04
updatedAt: 2026-07-10
---
MCP-сервер отказывается стартовать, а в логах мелькает что-то про `uvx`. История почти всегда одна: сервер запускается через `uvx` (или `uv`), а этой утилиты на компьютере просто нет. Чинится за пару минут. Ниже разберём, что это за инструмент, как его ошибки выглядят на разных системах и как всё поправить.

## Что такое uv и uvx

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

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

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

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

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

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

**Windows** (cmd / PowerShell):

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

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

**macOS** (zsh / bash):

```text
zsh: command not found: uvx
```

```text
env: uvx: No such file or directory
```

**Linux** (bash):

```text
bash: uvx: command not found
```

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

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

```text
'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
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

### macOS

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

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

Или через [Homebrew](https://brew.sh/ru/), если он у вас уже стоит:

```bash
brew install uv
```

### Linux

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

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

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

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

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

```bash
uvx --version
```

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

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

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

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

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

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

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

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

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

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

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