Cursor 中 MCP 服务器报 "command not found" 的修复：环境变量与绝对路径排查

快速答案

• 核心结论：Cursor 的 GUI 配置不会继承终端完整的 PATH 环境变量，导致 npx、uvx 等命令找不到。解决方式是使用绝对路径或在 JSON 配置中显式声明 env 字段。
• 第一排查项：在终端执行 which npx（或 where npx）获取命令的绝对路径，然后在 Cursor 配置中直接使用该路径。
• 最小修复配置：在 .cursor/mcp.json 中为每个 MCP 服务器添加 env 字段，显式注入 PATH 变量（见下方代码块）。
• 适用边界：适用于 Cursor IDE 0.40+ 版本；Windows 使用 cmd /c 包装命令，macOS/Linux 直接使用绝对路径；若使用 npx 且网络受限，需预先全局安装包。

JSON
{
  "mcpServers": {
    "some-server": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@some/mcp-server"],
      "env": {
        "PATH": "/usr/local/bin:/usr/bin:/bin",
        "NODE_ENV": "production"
      }
    }
  }
}

问题复现：终端正常但 Cursor 报错

在 Cursor 中添加 MCP 服务器时，最常见的报错是：

command not found: npx
MCP server failed to start: ENOENT

但同样的命令在系统终端中执行却完全正常。这不是 Cursor 的 bug，而是环境变量继承机制的差异：

• 终端（如 iTerm、Windows Terminal）启动时会加载 shell 配置文件（.zshrc、.bashrc），其中包含 Node.js 等运行时添加到 PATH 的路径。
• Cursor 作为 GUI 应用，在 macOS 上通过 LaunchServices 启动、在 Windows 上通过资源管理器启动，不会读取 shell 配置文件，因此 PATH 往往只有系统默认值（/usr/bin:/bin:/usr/sbin:/sbin），缺少 /usr/local/bin、~/nvm/versions/node/... 等关键路径。

根因分析：Cursor 的配置加载机制

Cursor 支持两种 MCP 配置方式：

关键点：两种方式都不会自动加载你的 shell 配置。即使你在终端里 echo $PATH 看到一长串路径，Cursor 内部看到的可能只有 /usr/bin:/bin。

修复步骤：从诊断到解决

第一步：获取命令的绝对路径

在终端中执行：

BASH
# macOS / Linux
which npx uvx python3

# Windows (PowerShell)
where.exe npx
where.exe uvx

记录输出结果，例如 /usr/local/bin/npx 或 C:\Program Files\nodejs\npx.cmd。

第二步：修改配置（二选一）

方案 A：使用绝对路径（推荐）

JSON
{
  "mcpServers": {
    "github": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

方案 B：保留命令名 + 注入 PATH 环境变量

JSON
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "PATH": "/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin"
      }
    }
  }
}

注意：方案 B 的 env.PATH 必须包含 npx 所在目录。如果你使用 nvm 管理 Node.js，路径可能是 ~/nvm/versions/node/v20.11.0/bin，需要写绝对路径（/Users/yourname/nvm/...）。

第三步：Windows 特殊处理

Windows 下 npx 实际是 npx.cmd，Cursor 的 JSON 配置直接写 "command": "npx" 可能无法识别。需要包装一层：

JSON
{
  "mcpServers": {
    "github": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-github"]
    }
  }
}

或者使用 npx.cmd 的完整路径：

JSON
{
  "mcpServers": {
    "github": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

第四步：验证配置

修改配置后，在 Cursor 中执行：

1. 打开命令面板（Cmd+Shift+P / Ctrl+Shift+P）
2. 输入 "MCP: List Servers" 查看服务器状态
3. 如果仍然报错，点击服务器旁的刷新按钮，并查看 Cursor 的日志输出（Help → Toggle Developer Tools → Console）

常见报错与排查对照表

从 Claude Desktop 迁移配置的注意事项

Claude Desktop 的 MCP 配置位于 claude_desktop_config.json，格式与 Cursor 类似，但有两个关键差异：

1. 配置位置不同：Cursor 的项目级配置在 .cursor/mcp.json，用户级配置在 ~/.cursor/mcp.json；Claude Desktop 的配置在 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）。
2. 环境变量处理不同：Claude Desktop 同样不继承 shell 环境变量，但它的错误提示更明确（会显示完整的 stderr 输出）。迁移时，必须检查 command 是否为绝对路径，并补充 env 字段。

迁移示例：

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

// 迁移到 Cursor 后
{
  "mcpServers": {
    "filesystem": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/Documents"],
      "env": {
        "PATH": "/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

生产环境实践与避坑要点

1. 避免每次启动重新下载包

npx -y 每次都会检查并可能下载最新版本。对于生产环境，建议：

BASH
# 全局安装（一次性）
npm install -g @some/mcp-server

# 配置中直接使用命令名
{
  "mcpServers": {
    "some-server": {
      "command": "/usr/local/bin/some-mcp-server",
      "args": []
    }
  }
}

2. 敏感信息使用环境变量注入

不要在 mcp.json 中硬编码 API Key：

JSON
{
  "mcpServers": {
    "github": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

然后在启动 Cursor 前在 shell 中导出 GITHUB_TOKEN。注意：Cursor 不会自动读取 .env 文件，你需要手动在启动前设置，或使用 direnv 等工具。

3. 并发与端口冲突

多个 MCP 服务器可能监听同一端口。如果遇到 EADDRINUSE 错误，检查是否有残留进程：

BASH
lsof -i :PORT_NUMBER
kill -9 PID

4. 离线环境处理

离线环境无法使用 npx 下载包。解决方案：

1. 在有网环境执行 npm pack @some/mcp-server 获取 tarball
2. 拷贝到离线机器，执行 npm install -g /path/to/tarball.tgz
3. 配置中直接使用全局安装后的命令路径

常见问题 FAQ

Q: 为什么在 Cursor 中配置 MCP 服务器时出现 'command not found'，但在终端中运行正常？

A: Cursor 的 GUI 配置不会继承终端的完整环境变量，导致 PATH 不完整。解决方法是使用绝对路径，或在 JSON 配置中显式设置 env 字段。具体操作：在终端执行 which npx 获取绝对路径，替换配置中的 command 字段。

Q: 如何将 Claude Desktop 的 MCP 配置迁移到 Cursor？

A: 两者都支持 JSON 格式，但 Cursor 的配置位置和字段略有不同。通常需要将 command 和 args 复制到 Cursor 的 mcpServers 配置中，并确保路径和参数兼容。重点检查：1) command 是否为绝对路径；2) 是否需要补充 env.PATH；3) Windows 下是否需要 cmd /c 包装。

Q: 使用 npx 启动 MCP 服务器时，如何避免每次启动都重新下载包？

A: 可以预先全局安装包（npm install -g），然后直接使用命令名；或者使用 npx 的缓存机制，但建议在配置中指定具体版本以避免意外更新。例如："args": ["-y", "@some/mcp-server@1.2.3"]。