在 WSL 中安装 Cursor MCP 服务器以获得无缝开发体验

对于喜欢 Linux 工具的强大功能但在 Windows 上工作的开发人员来说，Windows Subsystem for Linux (WSL) 是一个改变游戏规则的工具。Cursor，这款 AI 优先的代码编辑器，可以通过与模型控制程序 (MCP) 服务器集成来进一步增强此设置。直接在你的 WSL 环境中运行这些 MCP 服务器可以使你的开发工作流程保持整洁和统一。本指南将引导你完成配置 Cursor 以使用在 WSL 中运行的 MCP 服务器的步骤。

MCP 是什么？

MCP (Model Control Protocol，模型控制协议) 是一种协议，允许像 Cursor 中的 AI 模型安全地与各种工具和数据源进行交互。这些工具，或称"MCP 服务器"，可以执行诸如 Web 搜索、文件系统操作甚至浏览器交互等操作，从而为 AI 提供更丰富的上下文和更多功能。

为什么要在 WSL 中运行 MCP 服务器？

一致性： 将你的整个开发工具链保持在你习惯的 Linux 环境中。
简化的路径： 避免在访问文件系统的工具中处理 Windows 与 Linux 路径转换的复杂性。
利用 Linux 特定的工具： 某些 MCP 服务器或其依赖项可能在 Linux 环境中运行得更好或仅能在 Linux 环境中运行。
隔离性： 将 MCP 服务器所需的 Node.js 版本和其他依赖项管理在 WSL 内部，与你的 Windows 系统分开。

先决条件

在开始之前，请确保你具备以下条件：

已安装 WSL： 一个正常工作的 WSL，并已设置好一个 Linux 发行版 (例如 Ubuntu)。
WSL 中的 Node.js 和 npx： Node.js 和 npx (npm 自带) 必须安装在你的 WSL 发行版内部。
- 强烈建议在 WSL 中使用像 nvm (Node Version Manager) 这样的版本管理器来管理 Node.js 版本。这有助于避免权限问题，并允许轻松切换 Node.js 版本。
Cursor IDE： 已安装在你的 Windows 计算机上。

配置步骤

在 WSL 中运行 MCP 服务器的关键是告诉 Cursor 如何使用 WSL 命令行界面启动它们。这通过编辑 mcp.json 文件来完成。

1. 定位或创建 `mcp.json`

Cursor将其 MCP 服务器配置存储在一个名为 mcp.json 的文件中。在 Windows 上，你通常可以在以下位置找到此文件：

C:\\Users\\<YourUserName>\\.cursor\\mcp.json

将 <YourUserName> 替换为你的实际 Windows 用户名。如果该文件或 .cursor 目录不存在，Cursor 可能会在你首次尝试通过其 UI 添加 MCP 服务器时创建它，或者你可能需要手动创建它。

2. 理解 `mcp.json` 结构

mcp.json 文件包含一个 JSON 对象，其中 mcpServers下的每个键代表一个已配置的 MCP 服务器。这是一个基本结构：

{
  "mcpServers": {
    "your-mcp-server-name": { // 你的 MCP 服务器名称
      "command": "executable_or_wsl", // 可执行文件或 wsl
      "args": ["argument1", "argument2", "command_to_run_in_wsl"], // 参数
      "enabled": true // 是否启用
      // 其他选项，如 "env", "workingDirectory" 也可以指定
    }
  }
}

3. WSL 的核心配置

要在 WSL 中运行 MCP 服务器 (通常是一个 npx 命令)，你需要按如下方式配置服务器条目：

"command": 将此设置为 "wsl"。
"args": 这将是一个数组。第一个元素告诉 wsl 使用哪个 shell 并执行一个命令字符串。最后一个元素是命令字符串本身。
- bash 示例: ["bash", "-c", "npx @some-mcp/package --port {{port}}"]
- zsh 示例: ["zsh", "-c", "npx @some-mcp/package --port {{port}}"]
(注意: {{port}} 是 Cursor 通常用来注入端口号供 MCP 服务器侦听的占位符。如果 MCP 服务器需要端口，请查阅其特定文档。)

4. 处理 Shell 环境 (对 `nvm` 用户至关重要)

一个常见的问题是，当 Cursor 调用 wsl ... npx ... 时，可能找不到 npx 命令，或者它可能未使用你期望的 Node.js 版本 (特别是如果你使用 nvm)。这是因为 wsl 启动的非交互式 shell 会话可能不会加载你的完整 shell 配置文件 (例如 .bashrc、.zshrc)，而 nvm 和其他 PATH 修改通常是在这些文件中配置的。

以下是两种可靠的解决方案：

解决方案 A：使用 Shell 脚本 (推荐，更清晰)

此方法涉及在你的 WSL 环境中创建一个小型 shell 脚本，该脚本负责设置环境然后运行 npx 命令。

在 WSL 中创建脚本： 打开你的 WSL 终端并创建一个脚本，例如 ~/run_browsermcp.sh：

#!/bin/zsh
# 如果你使用 bash，则使用 #!/bin/bash

# 加载 shell 的 rc 文件以配置 nvm 和其他环境变量
# 如果需要，请调整 rc 文件的路径
if [ -f "$HOME/.zshrc" ]; then
  source "$HOME/.zshrc"
elif [ -f "$HOME/.bashrc" ]; then
  source "$HOME/.bashrc"
fi

# 用于调试：检查正在使用哪个 npx 以及 Node 版本
# which npx
# node -v

# 你的 MCP 服务器的实际 npx 命令
# 替换为你需要的特定 MCP 服务器命令
npx @browsermcp/mcp@latest --port {{port}}

一个例子：

#!/bin/sh
zsh -c "source /home/vector/.zshrc && npx @browsermcp/mcp@latest"

(注意：直接调用 zsh -c。如果使用此方法，请确保脚本本身是可执行的，并且 .zshrc 的路径正确。)

使脚本可执行： 在你的 WSL 终端中：
```
chmod +x ~/run_browsermcp.sh
```
(根据需要调整脚本名称)。

配置 mcp.json： 修改你的 mcp.json 以执行此脚本。如果你的 WSL 用户名是 vector，你使用 zsh，并且脚本位于 /home/vector/run_browsermcp.sh：

{
  "mcpServers": {
    "browsermcp-wsl": { // 给它一个描述性的名称
      "command": "wsl",
      "args": [
        "zsh", // 或 "bash"
        "-c",
        "/home/vector/run_browsermcp.sh" // WSL 中脚本的完整路径
      ],
      "enabled": true
    }
  }
}

这与你为 browsermcp 提供的 mcp.json 结构相匹配：

{
  "mcpServers": {
    "browsermcp": {
      "command": "wsl",
      "args": [
        "zsh",
        "-c",
        "/home/vector/browsermcp.sh" // 你示例中的路径
      ]
    }
  }
}

解决方案 B：直接在 mcp.json 中加载 (Sourcing)

你可以尝试直接在 args 中加载你的 rc 文件。根据 rc 文件的复杂性，这有时可能不太可靠，但如果可行，则更为简洁。

{
  "mcpServers": {
    "my-mcp-server-bash": {
      "command": "wsl",
      "args": [
        "bash",
        "-ic", // 注意：-i 表示交互式，可能有助于加载 rc 文件
        "source ~/.bashrc && npx @some-mcp/package --port {{port}}"
      ],
      "enabled": true
    },
    "my-mcp-server-zsh": {
      "command": "wsl",
      "args": [
        "zsh",
        "-ic", // 注意：-i 表示交互式
        "source ~/.zshrc && npx @some-mcp/package --port {{port}}"
      ],
      "enabled": true
    }
  }
}

如果使用 nvm 并且上述方法仍然失败，你可能需要提供 nvm.sh 和由 nvm 安装的 npx 可执行文件的绝对路径：

{
  "mcpServers": {
    "my-mcp-nvm-direct": {
      "command": "wsl",
      "args": [
        "bash", // 或 "zsh"
        "-c",
        // 相应地替换 /home/your_user 和 YOUR_NODE_VERSION
        "source /home/your_user/.nvm/nvm.sh && /home/your_user/.nvm/versions/node/vXX.YY.Z/bin/npx @some-mcp/package --port {{port}}"
      ],
      "enabled": true
    }
  }
}

要在加载 nvm.sh 并使用 nvm use 选择 Node 版本后找到 npx 的完整路径，请在 WSL 终端中运行 which npx。

5. 示例：配置浏览器交互 MCP

让我们以 @browsermcp/mcp 为例，因为它很常见。

使用解决方案 A (如前定义的 shell 脚本 ~/run_browsermcp.sh)：

{
  "mcpServers": {
    "browsermcp-wsl": {
      "command": "wsl",
      "args": [
        "zsh", // 如果你的脚本和环境使用 bash，则为 "bash"
        "-c",
        "/home/YOUR_WSL_USERNAME/run_browsermcp.sh" // 调整路径
      ],
      "enabled": true,
      "env": {
         // 可选：如果 MCP 服务器需要特定的环境变量
         // "DEBUG": "true"
      }
    }
  }
}

请记住将 YOUR_WSL_USERNAME 替换为你的实际 WSL 用户名。

验证

保存 mcp.json 后：

重新启动 Cursor 或转到 Cursor 设置 -> 功能 -> MCP，然后单击某个服务器旁边或所有 MCP 服务器的刷新图标。
MCP 设置中服务器名称旁边的绿点表示 Cursor 已成功连接到它。
你可能会看到一个由 wsl 启动的新终端窗口弹出。此窗口必须保持打开状态才能使 MCP 服务器正常工作。这是以这种方式运行 MCP 服务器时的预期行为。
通过要求 Cursor 执行使用该 MCP 服务器的操作来测试它 (例如，对于 @browsermcp/mcp，在设置好配套的浏览器扩展后，要求它"截取当前浏览器标签页的屏幕截图")。

故障排除

npx: command not found 或 Node 版本错误： 这几乎总是意味着 WSL 内的 shell 环境未正确设置。
- 仔细检查 shell 脚本或直接命令中的路径。
- 确保 nvm 已正确加载。
- 如果使用 nvm，请尝试在脚本或命令字符串的开头明确添加 export NVM_DIR="$HOME/.nvm" 和 [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"。
- 验证 node 和 npx 确实已安装在你的 WSL 发行版中，并且在加载 rc 文件后可以访问。
MCP 服务器无法连接 (没有绿点)：
- 检查弹出的 WSL 终端窗口中的输出。它可能包含错误消息。
- 确保 MCP 服务器的 npx 命令正确，并包含任何必要的参数，如 --port {{port}}。某些 MCP 如果未指定端口，可能会自动分配端口。
- 防火墙问题：在使用 WSL2 的网络模型时不太常见，但请确保 Windows 防火墙没有阻止与 WSL 的连接。
“空白"终端窗口： 如前所述，每个通过 wsl 启动的 MCP 服务器都会打开一个终端窗口。这是正常的。关闭它将停止 MCP 服务器。

结论

配置 Cursor 以在你的 WSL 环境中运行 MCP 服务器，可在 Windows 上提供简化且强大的开发设置。通过仔细设置你的 mcp.json 并确保正确加载 WSL shell 环境，你可以将 AI 功能无缝集成到基于 Linux 的工作流程中。对于处理由 nvm 等工具管理的环境，shell 脚本方法 (解决方案 A) 通常是最稳健的方法。

MCP 是什么？#

为什么要在 WSL 中运行 MCP 服务器？#

先决条件#

配置步骤#

1. 定位或创建 mcp.json#

2. 理解 mcp.json 结构#

3. WSL 的核心配置#

4. 处理 Shell 环境 (对 nvm 用户至关重要)#

5. 示例：配置浏览器交互 MCP#

验证#

故障排除#

结论#

祝你使用 Cursor 和 WSL 编码愉快！#