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

Ставите MCP-сервер по инструкции, а он молча не поднимается. В логах клиента мелькает npx и загадочное ENOENT или command not found. Тут важная тонкость: npx идёт в комплекте с Node.js, а Node сегодня стоит почти на любой машине, где вообще что-то разрабатывают. То есть сама утилита у вас, скорее всего, уже есть. Проблема в другом: клиент её не находит. И почти всегда виноват PATH. Про него и поговорим подробно.

Что такое npx

npx это спутник npm. Он скачивает npm-пакет во временную папку, запускает его и не тянет ничего в глобальные зависимости. Отдельно его не ставят: он едет вместе с Node.js, внутри npm. Есть node, значит почти наверняка есть и npx.

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

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/Documents"]
    }
  }
}

Флаг -y тут не для красоты: он велит npx не переспрашивать, а молча поставить пакет, если того ещё нет в кэше. Когда клиент (Claude Desktop, Cursor, VS Code) стартует, он читает конфиг и выполняет npx -y @modelcontextprotocol/server-filesystem .... Не смог найти npx, значит сервер не запустился, а вы получили ошибку в логах.

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

Формулировка зависит от системы и клиента, но суть везде одна: команду не нашли.

Windows (cmd / PowerShell):

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

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

macOS (zsh / bash):

zsh: command not found: npx

env: node: No such file or directory

Linux (bash):

bash: npx: command not found

В логах клиента всё это часто завёрнуто в spawn npx ENOENT или MCP server exited with code 1. Формулировки разные, смысл один: по имени npx система ничего не нашла.

Почему клиент не видит npx: всё дело в PATH

Проверьте первым делом, что npx вообще на месте. Откройте терминал и наберите:

npx -v

Если версия вывелась, а сервер всё равно падает, значит npx у вас есть и переустанавливать Node незачем. Вся загвоздка в PATH.

PATH это переменная окружения со списком папок, где система ищет исполняемые файлы. Набрали npx, и система идёт по этому списку папка за папкой, пока не наткнётся на файл npx. Нет нужной папки в списке, и для системы команды npx не существует, хотя физически файл лежит на диске.

Хитрость в том, что у терминала и у приложения с графическим интерфейсом PATH разный. Когда вы открываете терминал, он подгружает ваши настройки из .zshrc или .bashrc, а там дописаны пути до Node и всего остального. Поэтому в терминале npx работает. А вот Claude Desktop, Cursor и прочие GUI-приложения запускаются в обход этих настроек, с урезанным системным PATH, где про вашу папку с Node ничего не сказано. Отсюда и command not found при живом и рабочем npx в соседнем окне.

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

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

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

"command": "/usr/local/bin/npx"

На Windows путь будет вида "C:\\Program Files\\nodejs\\npx.cmd". Тут два нюанса: в JSON обратные слэши обязательно удваиваются, а у файла расширение .cmd.

После правки конфига полностью перезапустите клиент. Не свернуть, а закрыть и открыть заново, иначе он подтянет старый конфиг.

Особый случай: Node через nvm

Если Node ставили через nvm, вы почти обречены наступить на эти грабли. nvm прячет каждую версию Node в свою папку вроде ~/.nvm/versions/node/v22.11.0/bin и добавляет её в PATH только когда терминал подгружает .zshrc или .bashrc. GUI-приложения эти файлы не читают, так что node они не находят в упор, хотя в терминале всё летает. Отсюда, кстати, и ошибка env: node: No such file or directory: файл npx нашёлся, а node, которым он запускается, нет.

Решение то же самое, полный путь через which npx в конфиг. Только держите в голове: после nvm use другой версии путь поменяется, и конфиг придётся поправить заново.

Если Node.js всё-таки не установлен

Бывает и так, что npx -v честно отвечает command not found, тогда Node действительно нет и его надо поставить. Берите LTS-версию, она стабильнее.

• Windows: установщик с nodejs.org или winget install OpenJS.NodeJS.LTS.
• macOS: brew install node или .pkg-установщик с nodejs.org.
• Linux: проще всего через nvm (nvm install --lts), без sudo и конфликтов с системными пакетами.

Потом перезапустите терминал (установщик правит PATH, но открытые окна об этом не знают), проверьте node -v и npx -v, и полностью перезапустите клиент. После этого сервер, который падал с npx not found, поднимется нормально.