claude-wsl-mcp

让 Windows 上的 Claude Desktop 通过 MCP 直接在 WSL（Ubuntu） 里干活：执行 shell 命令、读写文件、跑 git / npm / node / python， 并默认把 Windows 宿主机的文件隔离在外。

• 不需要在 WSL 里装 Claude Code，也不用重新登录——用的就是 Windows 上已登录的 Claude Desktop；

• 在对话里直接说“检查当前项目 git 状态”“安装依赖”“运行测试”“修改这个 Python 文件”“启动服务”；

• Chat 标签页和 Code 标签页（本地会话）都能用：Claude Desktop 会把 claude_desktop_config.json 里的服务器同时带给两者。

工作原理

flowchart LR
    subgraph Windows
        CD["Claude Desktop"]
        WX["wsl.exe<br/>拉起进程、转发 stdin/stdout"]
    end
    subgraph WSL["WSL2 · Ubuntu"]
        L["bin/claude-wsl-mcp<br/>启动脚本"]
        S["MCP Server（Python · 官方 SDK）<br/>沙箱：私有挂载命名空间"]
        T["bash · git · npm · node · python<br/>文件读写"]
    end
    CD -- "claude_desktop_config.json<br/>mcpServers.wsl" --> WX
    WX -- "MCP JSON-RPC over stdio" --> L --> S --> T

调用链上每一环负责的事：

服务器随 Claude Desktop 启动而启动、退出而退出，由 Claude Desktop 自动连接；后台任务（开发服务器等）独立于服务器进程，Claude Desktop 重启后仍在运行且可继续查看、停止。

Related MCP server: Local Dev Bridge MCP

工具

安全边界

默认配置下，Claude 通过本服务器碰不到 Windows 宿主机的文件，也调不起 Windows 程序。 这不是靠检查命令字符串（run_command 能跑任意命令，字符串检查形同虚设），而是在操作系统层面做的：

1. 服务器以 root 启动后立即 unshare 出私有挂载命名空间，之后的挂载改动只影响服务器及其子进程，你自己开的 WSL 终端不受影响；

2. Windows 盘（/mnt/c 等 drvfs 挂载）默认卸载并盖上只读空目录（hidden），可改为只读（readonly）或不限制（readwrite）；

3. 禁用互操作：/run/WSL 盖一层空 tmpfs、去掉 WSL_INTEROP，cmd.exe、powershell.exe 等拉不起来；PATH 里的 Windows 目录被剔除，npm、python 不会误用 Windows 版；

4. /proc/sys、/sys 改只读；子进程的能力边界集去掉 sys_admin、sys_ptrace 等——即使是 root 也无法重新挂载、nsenter、或经 /proc/<pid>/root 穿回宿主命名空间；

5. 文件类工具另有路径策略：拒绝 C:\... 形式的 Windows 路径，写入与删除只允许在 workspace_root 与 extra_writable_roots 之内，符号链接先解析再判断。

沙箱建立失败时服务器拒绝启动，不会降级运行。

不在防护范围内：服务器里的命令以 WSL 的 root 身份运行，可以修改 WSL 自身的任何文件；root 也可以请特权守护进程代劳（docker run -v /mnt/c:...、systemd-run、cron），这些进程在沙箱之外。 需要时把相应套接字加入 sandbox.hide_paths，例如 ["/run/docker.sock"]。

安装

前提：Windows 10/11 + WSL2 发行版（在 Ubuntu 24.04 上验证）、Python 3.10+（含 python3-venv）、Claude Desktop 已安装并至少打开过一次。

# 在 WSL 里（root）
git clone <本仓库地址> ~/project/claude-wsl-mcp
cd ~/project/claude-wsl-mcp
./install.sh --project ~/project/你的项目

install.sh 会：创建 .venv 并安装依赖 → 生成 ~/.config/claude-wsl-mcp/config.toml（已存在则沿用）→ 在独立命名空间里自检沙箱 → 把服务器写进 Windows 版 Claude Desktop 的配置（自动识别 MSIX 版与传统安装版的配置位置，只改 mcpServers.wsl 一项，改前备份）。

然后完全退出 Claude Desktop（任务栏右下角托盘里右键 Claude 图标 → 退出），重新打开即可。只关窗口不算退出。

登记进 Claude Desktop 的内容形如：

{
  "mcpServers": {
    "wsl": {
      "command": "C:\\Windows\\System32\\wsl.exe",
      "args": ["-d", "Ubuntu-24.04", "-u", "root", "--cd", "~", "--exec", "/root/project/claude-wsl-mcp/bin/claude-wsl-mcp"]
    }
  }
}

Node.js 不是本服务器的依赖；但若希望 Claude 在 WSL 里跑 npm/node，需要在 WSL 里装 Linux 版 Node（否则 npm 可能解析到 Windows 版，而沙箱会把它屏蔽掉）。

配置

~/.config/claude-wsl-mcp/config.toml（可用环境变量 CLAUDE_WSL_MCP_CONFIG 或 --config 指定别处）：

换项目：改 current_project 这一行即可，无需重启；或直接对 Claude 说“切换到 xxx 项目”。

验证

• 在 Claude Desktop 里说：“调用 wsl_info”——输出里有 microsoft-standard-WSL2 内核、发行版名、沙箱状态；

• Windows 侧端到端测试（按 Claude Desktop 的方式拉起服务器并逐个调用工具）：

  powershell -ExecutionPolicy Bypass -File \\wsl.localhost\Ubuntu-24.04\root\project\claude-wsl-mcp\windows\smoke-test.ps1

• WSL 侧自检：bin/claude-wsl-mcp --check

排障

• Claude Desktop 里没出现工具：确认是完全退出后重开的；看日志 mcp-server-wsl.log（服务器写到 stderr 的内容也在里面）。 MSIX 版在 %LOCALAPPDATA%\Packages\Claude_<ID>\LocalCache\Local\Claude\logs\（实测）；传统安装版对应 %LOCALAPPDATA%\Claude\logs\，较旧版本在 %APPDATA%\Claude\logs\。 正常连上时日志里有 Server started and connected successfully 和 tools/list 的应答；Desktop 启动时先拉起一次又立即关闭，属正常现象。

• 日志里“沙箱建立失败，拒绝启动”：服务器必须以 root 启动（配置里的 -u root）。

• 命令报 Read-only file system / 找不到 /mnt/c：这是沙箱在起作用；确需访问 Windows 盘就改 sandbox.windows_drives，然后重启 Claude Desktop。

• 命令超时：run_command 默认 120 秒；长期运行的程序用 start_background。

卸载

.venv/bin/python -m claude_wsl_mcp.desktop_config --remove   # 从 Claude Desktop 配置里移除
rm -rf ~/.config/claude-wsl-mcp ~/.local/state/claude-wsl-mcp  # 配置与状态（后台任务日志等）

与 Code 标签页自带的 WSL 会话的区别

Claude Desktop 的 Code 标签页也能直接开 WSL 会话（它会在发行版里部署 Claude Code），但仅限 Code 标签页，且该模式下不支持连接器与插件。 本项目走标准 MCP，Chat 与 Code 标签页（本地会话）都能用，并额外提供 Windows 宿主机文件隔离。

开发

.venv/bin/python -m pytest -q     # 端到端用例需要在 WSL 里以 root 运行