MCP spawn npx ENOENT: Fix PATH on macOS, Windows, and Linux
spawn npx ENOENT means the MCP client cannot locate the executable it was told to launch; the server package has not started yet.
If MCP reports spawn npx ENOENT, the client cannot find the npx executable in the environment used to start the server. The package has not launched yet, so debug the client’s PATH and spawn arguments before changing server code or reinstalling packages.
Table of contents
- What ENOENT means here
- The 60-second proof
- macOS fixes
- Windows fixes
- Linux fixes
- How to prove the server is healthy
- FAQ
What ENOENT means here
The operating system could not find npx at process-spawn time; MCP initialization never began. ENOENT identifies a missing file or directory in the operating-system call, so this error points first to executable lookup rather than to the MCP server package itself. See the Node.js common system errors documentation.
The important distinction is where the lookup happens. Your terminal may know about a Node installation loaded by a shell profile, while a graphical client, service, container, or editor process may receive a different PATH. The client then tries to spawn npx, fails before the package starts, and cannot reach MCP’s initialization exchange.
Treat the error as an environment mismatch:
| Evidence | What it indicates | Next action |
|---|---|---|
npx is missing from the client environment | Executable lookup failed | Fix the runtime PATH or command |
Absolute npx path works temporarily | The package and arguments may be reachable | Make the runtime PATH durable |
| A new protocol error appears | The process now starts | Continue with MCP diagnostics |
initialize succeeds but tools are absent | Startup passed | Check server configuration and tool discovery |
Preserve the original error and configuration before editing anything. Change one layer at a time: executable name, environment, working directory, arguments, then MCP protocol behavior.
The 60-second proof
Compare which npx or where npx with the environment inherited by the GUI client, then run the exact configured command manually. This separates “the executable cannot be found” from “the server starts but fails later.”
Run these read-only checks in the terminal where the command is known to work:
which npx
command -v npx
npx --version
node --version
printenv PATH
pwd
On Windows, use the shell that matches the client’s configuration:
Get-Command npx
Get-Command npx.cmd
npx --version
node --version
$env:Path
Get-Location
Then inspect the client’s configured command and arguments. Keep the command and every argument separate where the client supports an argument array. Do not silently add shell syntax, quoting, or a different working directory.
As a diagnostic, replace npx with the absolute path returned by which, command -v, or where. If that allows the process to start, the result is useful evidence, not the final design. The durable fix is to make the Node installation visible to the client process itself. The MCP debugging guide recommends narrowing failures with direct, observable checks rather than treating every startup error as a server defect.
macOS fixes
Finder-launched apps often miss shell-managed Node paths, so verify Homebrew, nvm, fnm, or Volta paths explicitly. The key question is whether the app receives the same PATH as the terminal where npx works.
First record the terminal result of:
command -v npx
node --version
npx --version
printenv PATH
Next compare it with the environment available to the MCP client. If the client has an environment setting, provide the Node installation’s bin directory there. If it supports a complete executable path, use the path returned by command -v npx only to confirm the diagnosis, then configure the client to inherit or define the runtime path consistently.
Be especially careful when the terminal loads Node through nvm, fnm, or Volta. Those tools can select a runtime during shell startup, while an app opened from Finder may not run the same shell initialization. Homebrew-managed Node installations can create the same distinction if their bin directory is present in the terminal but absent from the app environment.
Restart the client after changing its environment, then repeat the exact configured command. A related MCP Router Electron PATH issue illustrates why an Electron-based application can expose a different PATH from the interactive shell. Do not weaken macOS security controls or modify certificates to hide an executable lookup error.
Windows fixes
Windows may require cmd /c or npx.cmd depending on how the client spawns child processes; keep each argument separate. Test both the command resolution and the client’s process-spawn behavior before changing the server package.
In PowerShell, inspect both names:
Get-Command npx
Get-Command npx.cmd
where.exe npx
where.exe npx.cmd
If npx resolves but the client still reports ENOENT, configure the command as npx.cmd when the client launches executables directly. If the client expects a shell command, use its documented cmd /c form and keep the remaining command arguments in their own positions. Avoid placing the entire command, flags, and arguments into one opaque string unless that client explicitly requires it.
Also compare the PATH visible to the client with $env:Path in PowerShell or echo %PATH% in Command Prompt. A Node installation available to one user or shell may not be available to the process that launched the MCP client.
The VS Code spawn npx ENOENT issue is useful evidence that client-side process spawning can be the failing layer. Once npx.cmd or the appropriate shell path resolves, preserve that configuration and look for the next error instead of reinstalling immediately.
Linux fixes
Desktop launchers, systemd services, containers, and shells can each have different PATH values and working directories. Verify the exact execution context rather than assuming that a successful interactive shell test represents every Linux process.
From the working shell, record:
command -v npx
npx --version
node --version
printenv PATH
pwd
Then inspect the launcher, service, or container configuration that starts the MCP client. Confirm that its environment includes the directory containing npx, and confirm that its working directory is valid for the configured server arguments. For a service or container, the environment must be defined where that process starts; editing only an interactive shell profile may have no effect.
Use the absolute executable path temporarily to distinguish PATH failure from argument failure. If the absolute path works, restore a normal command configuration and make the runtime directory available to the client’s environment. If the same ENOENT remains, check whether the client is attempting to spawn a different command than the one shown in its visible configuration.
MCP transports define how the client and server communicate after startup, while this error occurs before that exchange. The MCP transport specification helps keep the boundary clear: first make the process launch, then diagnose transport and protocol behavior.
How to prove the server is healthy
After the executable resolves, validate initialize and tools/list; a new error means you moved past ENOENT. A successful process launch proves only that the operating system found the executable, not that the server completed the MCP lifecycle.
Run the exact configured command manually and observe whether it remains available for the configured transport. For a stdio server, do not type arbitrary text into the process stream; preserve the protocol framing expected by the client. MCPtrove’s stdio transport glossary entry explains the role of that channel.
Then confirm the sequence:
- The client starts the configured executable.
- The server responds to
initialize. - The client completes the initialization exchange.
- The client requests
tools/list. - The expected tools appear without a separate spawn error.
The MCP lifecycle specification defines initialization as the negotiation boundary between client and server (MCP lifecycle). JSON-RPC supplies the request and response structure used by these messages (JSON-RPC 2.0). If initialize fails, inspect protocol input, versions, and transport configuration. If tools/list fails, inspect server startup and tool registration. The MCP Inspector repository provides a focused way to inspect MCP server behavior.
Once the executable and protocol work, use MCPtrove’s Config Doctor and Config Validator to check configuration systematically. For a new server setup, the guide on how to add an MCP server is the practical next step.