AgentHubAgentHub

使用指南·MCP

MCP 环境准备教程：Windows / macOS 安装 Node.js，解决 npx 不是内部或外部命令

90% 的 MCP 安装失败卡在环境上：没有 Node.js、提示 npx 不是内部或外部命令、国内下载超时。本文从零装好 Node.js 与 Python 两条路线，配好国内镜像源，并逐一解决 npx 找不到、uvx 太慢、公司代理三大高频报错。

先搞懂：为什么装 MCP 前要装环境

你在 MCP 配置里最常见的两个开头是 npx 和 uvx，它们不是 MCP 本身，而是启动器：

  • npx：随 Node.js 附带，负责把 npm 上的 MCP 包下载并立刻运行（比如 npx -y @modelcontextprotocol/server-filesystem）
  • uvx：随 Python 工具 uv 附带，作用相同，只是面向 PyPI 上的 MCP 包（比如 uvx mcp-server-fetch）

所以「装环境」= 让电脑里有 npx 或 uvx 可用。一个 MCP 只需要其中一条路线，看它详情页给的配置以哪个开头就装哪个；两个都装则通吃绝大多数。

路线 A：安装 Node.js（推荐大多数人先装这个）

Windows

  1. 打开 nodejs.org/zh-cn，下载 LTS 版本（长期支持，别下 Current）
  2. 运行安装程序，保持默认选项一路「下一步」——务必勾选 Add to PATH（默认已勾）
  3. 装完关闭并重新打开终端（老终端不会自动刷新 PATH）

macOS

  • 方式一（简单）：同样从官网下载 .pkg 安装包，双击安装
  • 方式二（推荐常用终端的人）：brew install node

验证（关键一步）

打开 PowerShell（Windows）或终端（macOS），逐条执行：

node -v    # 应输出 v20.x / v22.x 之类
npm -v     # 应输出 10.x 之类
npx -v     # 能输出一个版本号即成功

三个命令都有版本号输出，环境就绪。

国内下载慢？换 npm 镜像源

国内直连 npm 官方源经常超时，一条命令切到阿里镜像：

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

验证切换成功：

npm config get registry   # 输出上面那个地址即可

之后 npx -y xxx 首次下载 MCP 包的速度会明显改善。想切回官方源：npm config set registry https://registry.npmjs.org。

路线 B：Python 类 MCP 用 uv 安装

配置以 uvx 开头的 MCP（多为 Python 实现，如 fetch、sqlite）需要装 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

装完重开终端，执行 uvx --version 有输出即成功。uv 会自动管理 Python 版本，不需要你再单独装 Python。

提示：如果 curl 下载也慢，可以先装 Node.js 后用 npm i -g uv 类替代方案，或直接重跑安装脚本（通常第二次会快）。

三大高频报错逐个解

1. 「'npx' 不是内部或外部命令」

安装 Node.js 后没重开终端是头号原因——PATH 变更不影响已开着的窗口。关掉所有终端窗口重新打开再试。仍不行则说明安装时没勾 Add to PATH：重新运行安装程序修复，或手动把 Node.js 安装目录（默认 C:\Program Files\nodejs\）加入系统环境变量 PATH。

2. npx 首次运行卡住 / 超时

npx -y 第一次会真的去下载包，国内网络下可能几分钟无响应。解决顺序：① 按上一节换镜像源；② 手动预热一次——在终端直接跑配置里的完整命令（如 npx -y @modelcontextprotocol/server-filesystem ~），看到它启动说明下载成功，之后客户端里再配置就秒开了。

3. 公司网络 / 代理环境

企业代理常拦掉 npm 下载。给 npm 单独配代理：

npm config set proxy http://你的代理地址:端口
npm config set https-proxy http://你的代理地址:端口

离开公司网络后记得清除：npm config delete proxy 与 npm config delete https-proxy。

环境好了，下一步做什么

环境就绪后，按你的工具选一篇接入教程跟着做即可：

MCP 环境准备教程：Windows / macOS 安装 Node.js - AgentHub