wsl-rwx-7

WSL 的 MCP 服务器：read（读）/ write（写）/ execute（执行）—— rwx = 读 + 写 + 执行，7 = 二进制111。

这是一个 Model Context Protocol（MCP，模型上下文协议）服务器，让 AI Agent（智能体，如 Claude、Cursor、Trae、Cline 等）能在 Windows 环境下操作 WSL（Windows Subsystem for Linux）的文件系统：读取文件、写入文件、执行 shell 命令、在 Windows 路径与 Linux（WSL）路径之间相互转换。

主要解决两个痛点：① 从 Windows 读写 WSL 内的文件不方便；② 通过 PowerShell 执行 WSL（Linux）命令时，引号、$、反引号等特殊字符容易产生转义错误。本项目通过 bash -s + stdin 管道方式传递命令，彻底绕开 Windows 命令行解析，杜绝转义问题。

本项目 fork 自 webconsulting/mcp-server-wsl-filesystem，做了大量增强（新增 exec_command、copy_file、delete_file、convert_path 等工具），详见与原项目的差异。

English Note: wsl-rwx-7 is a MCP server that lets AI agents (Claude, Cursor, Trae, Cline, etc.) operate on WSL (Windows Subsystem for Linux) filesystems from Windows: read files, write files, run shell commands, and convert between Windows paths and Linux (WSL) paths. It solves two pain points: ① reading/writing WSL files from Windows is inconvenient; ② running WSL commands through PowerShell easily causes escaping errors with quotes, $, backticks, etc. This project passes commands via bash -s + stdin pipeline, completely bypassing Windows command-line parsing and eliminating escaping issues.  

本项目在开发过程中使用了 AI 编程助手辅助。

特性

• 读文件：read_file、read_file_by_parts、read_multiple_files、directory_tree、list_directory、get_file_info、search_in_files、search_files_by_name

• 写文件：write_file、edit_file、create_directory、move_file、copy_file、delete_file

• 执行 shell 命令：exec_command —— 使用 login shell，能够自动加载用户在~/.bashrc、~/.profile中定义的环境变量。

• 路径转换：convert_path 在 Windows 风格（C:\Users\foo）和 WSL 风格（/mnt/c/Users/foo）之间互转

• 安全转义：命令通过 bash -s 从 stdin 传入，不经 Windows 命令行，因此 $、`、"、'、\、空格、非 ASCII 内容都原样保留

• 路径白名单：文件操作限制在配置的目录内（exec_command 不受此限制，见安全说明）

• Agent 友好：所有工具的描述都包含 WSL 关键词，tool_search 一次搜索即可发现全部工具

Related MCP server: wsl-bridge-mcp

安装

注意：本 MCP 服务器运行在 Windows 端，但它操作的是 WSL 内的文件系统。因此白名单目录参数（如 /home/youruser/your/project）必须是 WSL 内的 Linux 路径，而非 Windows 路径。运行参数（--distro、白名单目录等）在下方 MCP 客户端配置 中设置。

方式一：npx 直接从 GitHub 运行（推荐）

无需克隆或安装，npx 会直接从 GitHub 拉取并运行：

{
  "mcpServers": {
    "wsl-rwx-7": {
      "command": "npx",
      "args": ["-y", "github:duringyl/wsl-rwx-7", "--distro=Ubuntu-24.04", "/home/user/project"],
      "transport": "stdio"
    }
  }
}

首次运行时 npx 会自动从 GitHub 下载源码并构建，请耐心等待。

方式二：克隆源码构建

git clone https://github.com/duringyl/wsl-rwx-7.git
cd wsl-rwx-7
npm install
npm run build

构建产物为 dist/index.js，在 mcp.json 中用 node dist/index.js 启动（见下方配置示例）。

MCP 客户端配置

在 MCP 客户端配置文件（如 mcp.json）中添加：

{
  "mcpServers": {
    "wsl-rwx-7": {
      "command": "npx",
      "args": [
        "-y",
        "github:duringyl/wsl-rwx-7",
        "--distro=Ubuntu-24.04",
        "/home/youruser/your/project"
      ],
      "transport": "stdio"
    }
  }
}

或者使用本地构建的 index.js（Windows 路径需用双反斜杠转义）：

{
  "mcpServers": {
    "wsl-rwx-7": {
      "command": "C:\\Path\\To\\nodejs\\node.exe",
      "args": [
        "C:\\Path\\To\\wsl-rwx-7\\dist\\index.js",
        "--distro=Ubuntu-24.04",
        "/home/youruser/your/project"
      ],
      "transport": "stdio"
    }
  }
}

启动参数

工具列表

读取类

• read_file —— 读取文件完整内容

• read_file_by_parts —— 分块读取大文件（每块约 95k 字符）

• read_multiple_files —— 一次调用读取多个文件

• list_directory —— 列出目录内容（类似 ls）

• directory_tree —— 递归目录树（JSON 格式）

• get_file_info —— 文件元数据（类似 stat）

• search_in_files —— 在文件中搜索文本（类似 grep）

• search_files_by_name —— 按名称模式查找文件/目录

写入类

• write_file —— 创建或覆盖文件

• edit_file —— 基于行的编辑，返回 diff

• create_directory —— 创建目录（mkdir -p）

• move_file —— 移动或重命名（mv）

• copy_file —— 复制（cp），默认拒绝覆盖已存在文件

• delete_file —— 删除文件或目录（rm -rf）

执行类

• exec_command —— 在 WSL 中执行 shell 命令（login shell，自动加载 ~/.profile）

工具类

• convert_path —— Windows 与 WSL 路径风格互转

• list_wsl_distributions —— 列出已安装的 WSL 发行版

• list_allowed_directories —— 列出配置的白名单目录

安全说明

• 文件操作（read_file、write_file、copy_file 等）限制在白名单目录内。

• exec_command 不受白名单限制——可以在 WSL 的任意位置执行命令。这是有意设计；白名单仅约束 cwd 参数。

• exec_command 中的危险命令过滤是尽力而为，不是安全边界。它会拦截明显的破坏性模式（rm -rf /、sudo、fork 炸弹等），但可以被绕过。请谨慎使用，请勿依赖它做安全防护。

• 所有命令通过 stdin 传给 bash（bash -s），内容中的特殊字符不会被 Windows shell 解释。

运行要求

• 已启用 WSL2 的 Windows

• 至少安装一个 WSL 发行版

• Node.js >= 18

开发

npm install
npm run build            # 编译 TypeScript 到 dist/
npm run watch            # 监听模式
node test/run-tests.mjs  # 运行测试套件

许可证

MIT，详见 LICENSE。

原始代码由 Web-C（mcp-server-wsl-filesystem）编写，该项目本身基于 Anthropic 的 MCP 服务器模板。Fork 改动由 duringyl 完成。

致谢

• webconsulting/mcp-server-wsl-filesystem —— 本项目 fork 的原项目

• Anthropic —— MCP 协议和服务器 SDK