Cursor MCP Spawn npx ENOENT: Causes and Fixes

Quick Answer

spawn npx ENOENT in Cursor means the Cursor process cannot find the npx executable when trying to launch your MCP server. It is almost never a problem with your MCP server code. The fix priority is:

1. Use the absolute path to npx in your MCP config instead of the bare npx command.
2. On Windows, use cmd /c npx ... or point to npx.cmd explicitly.
3. With nvm/fnm/volta, find the resolved path to npx after activating your Node version and hardcode it.
4. Check package name and args only after confirming the executable resolves correctly.

Cursor MCP Spawn npx ENOENT: 60-Second Fix Checklist

Run through this before diving deeper. Most cases are fixed at step 2 or 3.

• Confirm npx path: Run which npx (macOS/Linux) or where npx (Windows CMD)
• Confirm Node is installed: node --version and npm --version in a fresh terminal
• Check your MCP config: Is the command field set to bare npx? Replace with the absolute path.
• Windows only: Is command set to npx instead of cmd? Use cmd /c npx wrapper.
• Verify package name: Run npx -y your-package-name --help in a terminal manually
• Check args array: Each argument must be a separate string, not a single space-joined string
• Reload Cursor MCP: After config changes, restart the MCP server from Cursor settings
• Check Cursor MCP logs: Help > Toggle Developer Tools > Console for the raw error

What "spawn npx ENOENT" Actually Means

Node.js uses child_process.spawn() internally to launch MCP server processes. When Cursor tries to spawn npx and the operating system cannot locate the executable, Node throws:

Error: spawn npx ENOENT
    at Process.ChildProcess._handle.onexit (node:internal/child_process:285:19)

ENOENT is a POSIX error code: Error NO ENTry — the file or directory does not exist at the path that was searched. In this context, it means the OS searched every directory in the PATH environment variable and found no executable named npx.

This error fires before npx attempts to download or run any package. If you see ENOENT, your MCP package configuration is irrelevant until you resolve the executable path.

Why npx Works in Terminal but Cursor Still Shows ENOENT

This is the single most common source of confusion and the root cause in the majority of reported cases.

The problem: PATH in an interactive terminal shell is not the same PATH that GUI applications inherit.

When you open a terminal:

• The shell sources ~/.zshrc, ~/.bashrc, ~/.profile, or equivalent
• Those files add /usr/local/bin, ~/.nvm/versions/node/vX.Y.Z/bin, or whatever path your Node install lives under
• npx becomes resolvable

When Cursor launches (as a GUI app on macOS or Windows):

• It inherits the system-level PATH set at login time, which is typically /usr/bin:/bin:/usr/sbin:/sbin on macOS
• Your shell customizations are never loaded
• npx is nowhere in that short PATH
• Result: spawn npx ENOENT

Diagnostic flow:

# Step 1: What does your terminal see?
which npx
# Example: /Users/you/.nvm/versions/node/v20.11.0/bin/npx

# Step 2: What does Cursor's environment see?
# Add this temporarily to your MCP config to debug:
# command: "/bin/sh"
# args: ["-c", "echo $PATH > /tmp/cursor-path.txt"]
# Then read /tmp/cursor-path.txt

# Step 3: Is the npx directory in Cursor's PATH?
# If not, you must use the absolute path from Step 1

Fix Cursor MCP Spawn npx ENOENT on Windows

Windows deserves its own section because the failure mode is different and the fixes are Windows-specific.

Why Windows Fails Differently

On Windows, npx is not a standalone executable — it's a batch file (npx.cmd). Node's child_process.spawn() cannot directly execute .cmd files without going through cmd.exe. When Cursor tries to spawn('npx', [...]) on Windows, it fails because there is no npx.exe — only npx.cmd.

This is documented behavior in Node.js: batch files require the shell: true option or an explicit cmd.exe invocation.

Fix 1: Use cmd /c wrapper (Recommended)

Incorrect config (fails on Windows):

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}

Correct config for Windows:

{
  "mcpServers": {
    "my-server": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\you\\documents"]
    }
  }
}

cmd is always on the Windows system PATH, so spawn finds it. /c tells cmd to execute the following command and then exit. npx is then resolved by cmd.exe using its own PATH, which typically includes the npm global bin directory.

Fix 2: Absolute path to npx.cmd

If Fix 1 still fails (PATH not set correctly in cmd.exe either), use the absolute path:

# Find npx.cmd location in PowerShell
Get-Command npx | Select-Object -ExpandProperty Source
# Example output: C:\Users\you\AppData\Roaming\npm\npx.cmd

{
  "mcpServers": {
    "my-server": {
      "command": "C:\\Windows\\System32\\cmd.exe",
      "args": ["/c", "C:\\Users\\you\\AppData\\Roaming\\npm\\npx.cmd", "-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\you\\documents"]
    }
  }
}

JSON path escaping on Windows: Backslashes in JSON strings must be doubled. C:\Users\you becomes C:\\Users\\you. This is only relevant in JSON — do not apply this in shell commands.

Fix 3: Use Node directly instead of npx

If the MCP server is installed globally or locally, you can bypass npx entirely:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["C:\\Users\\you\\AppData\\Roaming\\npm\\node_modules\\@modelcontextprotocol\\server-filesystem\\dist\\index.js", "C:\\Users\\you\\documents"]
    }
  }
}

Find the entry point: npm root -g gives you the global node_modules directory.

Windows: Verification

# Verify cmd wrapper works correctly
cmd /c npx --version

# Verify the full config path manually
cmd /c "C:\Users\you\AppData\Roaming\npm\npx.cmd" --version

If both commands print a version number, your config should work.

Fix on macOS and Linux

Standard Node.js Install (Homebrew, nvm, system)

Step 1: Find the absolute path to npx.

which npx
# Common outputs:
# /usr/local/bin/npx       (Homebrew, older)
# /opt/homebrew/bin/npx    (Homebrew on Apple Silicon)
# /usr/bin/npx             (system Node)
# /home/user/.nvm/versions/node/v20.11.0/bin/npx  (nvm)

Step 2: Use that absolute path in your Cursor MCP configuration.

{
  "mcpServers": {
    "my-server": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/documents"]
    }
  }
}

nvm, fnm, or volta Users

Version managers install Node into version-specific directories. The path changes every time you switch Node versions. You have two clean options:

Option A: Symlink to a stable path (nvm)

# After setting your default nvm version:
nvm alias default 20
# The stable path for the default is:
~/.nvm/versions/node/$(nvm version default)/bin/npx
# But this path changes when you upgrade Node

Option B: Use the resolver script

Create a small shell script that resolves the active npx at runtime:

#!/bin/bash
# ~/.local/bin/npx-resolver.sh
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
exec npx "$@"

chmod +x ~/.local/bin/npx-resolver.sh

{
  "mcpServers": {
    "my-server": {
      "command": "/Users/you/.local/bin/npx-resolver.sh",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/documents"]
    }
  }
}

Volta users have it easier: Volta installs shims at ~/.volta/bin/npx, which is a stable path regardless of which Node version is active.

which npx  # Should show ~/.volta/bin/npx if volta is set up

Package Not Found vs spawn npx ENOENT

These are different errors requiring completely different fixes. Knowing which one you have saves significant debugging time.

Quick test: Run npx -y your-package-name --version in your terminal. If you get ENOENT, the problem is with npx itself. If npx runs but returns a 404 or module error, the problem is the package.

Cursor MCP Spawn npx ENOENT Troubleshooting Table

Incorrect vs Correct MCP Configuration Examples

Example 1: Bare command (fails on Windows, fails without PATH fix on macOS)

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/documents"]
    }
  }
}

Problems: npx not found in Cursor's PATH on most systems. ~/documents tilde expansion doesn't work in JSON config — use the full path.

Example 2: Correct macOS config

{
  "mcpServers": {
    "filesystem": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/documents"]
    }
  }
}

Example 3: Correct Windows config

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\you\\Documents"]
    }
  }
}

Example 4: Args packed into one string (always wrong)

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

Problem: Passing all args as a single string fails. Each argument must be its own array element.

Example 5: Environment variables in config

Cursor MCP configs support an env key for environment variables. Use this to pass API keys or to augment PATH:

{
  "mcpServers": {
    "my-server": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "my-mcp-server"],
      "env": {
        "MY_API_KEY": "your-key-here",
        "NODE_ENV": "production"
      }
    }
  }
}

Should You Run clear-npx-cache?

Short answer: Almost certainly not your problem if you're seeing spawn npx ENOENT.

npx clear-npx-cache (or npx --cache ~/.npm/_npx cache clearing) removes locally cached copies of packages that npx has previously downloaded. It helps when:

• A cached package version is corrupted
• You installed a package with npx and the cached binary is broken
• You need npx to re-fetch the latest version of a package

It does not help when:

• The npx executable itself cannot be found (ENOENT before any package logic runs)
• PATH is wrong
• You're on Windows and need the cmd wrapper

If you've seen recommendations to run npx clear-npx-cache for this error, those suggestions address a different failure mode. Run it only after you've confirmed that npx itself launches correctly and the error persists during package resolution.

# Only run this if npx itself works but package resolution fails:
npx clear-npx-cache
# Or manually:
rm -rf ~/.npm/_npx

Process Exits Immediately After Spawn

Once you've fixed ENOENT, you may encounter a new problem: the server process starts and immediately exits. This is a different error class.

Common causes:

• Wrong package name or version: npx downloads the wrong package or a package with a broken entry point
• Missing required arguments: Some MCP servers require specific args (like filesystem paths) and crash without them
• Missing environment variables: API keys or config not passed via env in the MCP config
• Node version incompatibility: Package requires Node 18+ but you're running 16

How to debug:

# Run the exact command from your MCP config manually
/opt/homebrew/bin/npx -y @modelcontextprotocol/server-filesystem /Users/you/documents

# Check exit code
echo $?

# Check stderr for crash output
/opt/homebrew/bin/npx -y @modelcontextprotocol/server-filesystem /Users/you/documents 2>&1

If the process crashes in terminal with the same args, the problem is the server or its configuration, not Cursor.

Testing Outside Cursor with MCP Inspector

Before debugging inside Cursor, confirm your MCP server works independently. The MCP Inspector is purpose-built for this.

# Install MCP Inspector
npx @modelcontextprotocol/inspector

# Or run it with your server directly
npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem /Users/you/documents

MCP Inspector starts a local UI (typically at http://localhost:5173) where you can:

• Confirm the server connects via stdio
• Call listTools to verify your tools are registered
• Call listResources if applicable
• View raw JSON-RPC messages

If Inspector connects and shows your tools, the server is healthy. If Cursor still fails, the problem is the Cursor MCP config or environment — not the server itself.

For deeper connection debugging after fixing ENOENT, see the guide on MCP server connection failures.

Connection Closed or Initialization Errors After Fixing ENOENT

After fixing the spawn error, some users hit a new error: the server connects but immediately closes, or Cursor reports a connection closed error. These are documented in detail in the MCP error -32000 connection closed guide.

The most common causes at this stage:

• The server doesn't implement the MCP handshake correctly (third-party package bug)
• The server writes to stdout in a non-JSON-RPC format, confusing Cursor's parser
• The server expects stdin to remain open but something closes it
• Transport mismatch: Cursor expects stdio but the server is trying to use SSE

Verify with MCP Inspector first. If Inspector also fails to initialize, the problem is in the server. If Inspector works fine, compare your Cursor config against the working Inspector invocation exactly.

How to Confirm the Fix

After making changes, use this sequence to confirm everything is working:

Step 1: Verify the executable resolves

# macOS/Linux
/opt/homebrew/bin/npx --version
# Should print something like: 10.x.x

# Windows CMD
cmd /c npx --version

Step 2: Verify the full MCP command runs in terminal

Copy the exact command and args from your MCP config and run them manually:

# Example from the macOS config
/opt/homebrew/bin/npx -y @modelcontextprotocol/server-filesystem /Users/you/documents
# Should start the server and wait for stdin input

Press Ctrl+C to exit. If it starts without errors, your config is correct.

Step 3: Reload MCP in Cursor

After editing .cursor/mcp.json (project-level) or the global Cursor MCP settings:

• Open Cursor Settings
• Navigate to the MCP section
• Click the restart/reload icon next to your server
• Check the server status indicator turns green

Step 4: Check Cursor Developer Console

Help > Toggle Developer Tools > Console tab

Search for your server name. If you still see ENOENT, the config change wasn't saved or reloaded. If you see a different error, you've moved past the spawn problem.

Step 5: Test a tool call

In a Cursor chat, reference your MCP server by asking it to use one of the expected tools. A successful response confirms end-to-end functionality.

Logs and Minimal Reproduction

If you need to report this issue or ask for help, gather these before posting:

# System info
node --version
npm --version
npx --version
which npx  # or: where npx on Windows
echo $PATH

# Your MCP config (redact secrets)
cat ~/.cursor/mcp.json
# or project-level:
cat .cursor/mcp.json

Also include:

• Your OS and version
• Cursor version (Help > About)
• The exact error message from Cursor's developer console
• Whether the command works in terminal

Prevention Best Practices

These habits prevent ENOENT errors from occurring in the first place:

Always use absolute paths in MCP config. Never rely on PATH resolution for the command field. What works today breaks the moment you upgrade Node or switch version managers.

On Windows, always use the cmd wrapper. Treat this as the default, not a workaround.

Pin your Node version. If you use nvm, set a default with nvm alias default X. If you use fnm, configure fnm default X. Then find the absolute path once and it stays stable until you change the default.

Avoid tilde (~) in paths inside JSON. Tilde expansion is a shell feature. JSON configs are not processed by a shell. Use /Users/yourname/... or /home/yourname/... explicitly.

Test new MCP configs in terminal first. Before adding a new server to Cursor, confirm the exact command and args work in a fresh terminal window. This takes 30 seconds and saves hours.

Use MCP Inspector for server validation. Before debugging Cursor behavior, confirm the server itself is healthy with MCP Inspector. This separates spawn/PATH problems from server initialization problems.

Document your npx path in your team's README. If you're sharing MCP configs in a repository, document the expected npx path per OS and recommend team members update it after Node changes. Alternatively, use a wrapper script that resolves dynamically.

Where to Look for Cursor MCP Logs

Cursor doesn't always surface MCP errors prominently. Check all three locations:

1. Developer Console: Help > Toggle Developer Tools > Console — raw Node.js errors including ENOENT
2. MCP Server Status: Cursor Settings > MCP — shows per-server connection status and recent error messages
3. System logs (macOS): Console.app, filter by Cursor for crash logs
4. Server stderr: Some MCP servers log to stderr. If you redirect stderr in your wrapper script, you can capture this to a file for debugging.

For persistent connection issues after ENOENT is resolved, the Cursor connection error guide covers the full range of post-spawn failures.

Official Sources

• Node.js child_process documentation - official process spawning, PATH lookup, and Windows .cmd execution behavior.
• npm npx documentation - official reference for running package binaries with npx.
• MCP transports specification - official stdio transport behavior for locally launched MCP servers.