AgentHubAgentHub

Guides·MCP

Prepare Your PC for MCP: Install Node.js on Windows/macOS and Fix 'npx is not recognized'

Most MCP install failures are environment problems: no Node.js, 'npx is not recognized', slow downloads in China. This guide walks through Node.js and Python setup, CN mirrors, and the three most common errors.

Why you need an environment first

Most MCP configs start with npx or uvx—these are launchers, not MCP itself:

  • npx ships with Node.js and downloads + runs npm-hosted MCP packages
  • uvx ships with the Python tool uv and does the same for PyPI packages

You only need one route: check what your MCP's config starts with and install that one. Installing both covers nearly everything.

Route A: Install Node.js (recommended)

Windows

  1. Download the LTS installer from nodejs.org
  2. Keep default options—make sure Add to PATH is checked
  3. Close and reopen your terminal afterwards

macOS

  • Simple: the official .pkg installer
  • Terminal people: brew install node

Verify

node -v
npm -v
npx -v

If all three print version numbers, you're ready.

Slow downloads? Switch to a CN mirror

Direct access to the npm registry often times out in mainland China. One command switches to the Aliyun mirror:

npm config set registry https://registry.npmmirror.com

Verify with npm config get registry. First-run npx -y downloads get noticeably faster.

Route B: uv for Python MCPs

Python-based MCPs (fetch, sqlite…) start with uvx and need uv:

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

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

Reopen the terminal; uvx --version printing a version means success. uv manages Python itself—no separate Python install needed.

Three most common errors

1. "'npx' is not recognized"

Almost always: the terminal was opened before installing Node.js. Close every terminal and reopen. Still failing? Rerun the installer with Add to PATH checked, or add C:\Program Files\nodejs\ to PATH manually.

2. npx hangs on first run

npx -y downloads the package on first use. Switch to the CN mirror above, or pre-warm it by running the exact command from the config in a plain terminal once—after it starts, the client will launch it instantly.

3. Corporate proxy

npm config set proxy http://PROXY:PORT
npm config set https-proxy http://PROXY:PORT

Remember to npm config delete proxy (and https-proxy) when you leave that network.

What's next

Once your environment is ready, pick your client:

Prepare Your PC for MCP: Install Node.js on - AgentHub