⚠️重要信息：
原有的Filesystem MCP Server已经可以通过在配置中简单地使用网络路径\\wsl.localhost\DistributionName作为参数来访问 WSL 文件。
例子：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "\\\\wsl.localhost\\Debian",
        "C:\\path\\to\\other\\allowed\\dir"
      ]
    }
  }
}

不过，该项目提供了专门针对 WSL Linux 发行版优化的替代实现。

虽然官方服务器通过使用 Node.js 的fs模块递归遍历目录来工作，但此实现利用WSL 内的本机 Linux 命令（例如find 、 grep等），从而使文件列表和内容搜索操作速度显著加快。

当处理大型目录树或搜索性能至关重要时，这尤其有用。

因此，尽管对于许多用例来说本机网络路径可能更简单，但对于寻求更好的性能或对索引和搜索逻辑进行更多自定义控制的WSL 用户来说，该项目仍然是一个有价值的解决方案。

WSL 的文件系统 MCP 服务器

Node.js 服务器实现了模型上下文协议 (MCP)，专为 Windows Subsystem for Linux (WSL) 中的文件系统操作而设计。
该项目是原始文件系统 MCP 服务器的一个分支，但完全针对 WSL 环境进行了重新设计。
与处理通用文件操作的原始项目不同，此版本专注于 WSL 下 Windows 和 Linux 发行版之间的无缝交互。
这两个项目兼容并且可以在同一系统上并行运行。

特征

• 从 Windows 访问任何 WSL 发行版

• 从 Windows 主机读取/写入 WSL 中的文件

• 在 WSL 中创建/列出/删除目录

• 在 WSL 文件系统之间移动文件/目录

• 在 WSL 中搜索文件

• 从 WSL 文件系统获取文件元数据

• 支持多个 WSL 发行版

注意：服务器仅允许在通过args指定的目录内进行操作。

Related MCP server: File Operations MCP Server

API

资源

• wsl -d <distrib> ：用于 WSL 发行版操作的命令

工具

• 读取文件

  • 从 WSL 读取文件的完整内容

  • 输入： path （字符串）

  • 将内容读取为 UTF-8 文本

• 读取多个文件

  • 从 WSL 同时读取多个文件

  • 输入： paths （字符串[]）

  • 读取失败不会停止整个操作

• 写入文件

  • 在 WSL 中创建或覆盖文件（谨慎使用）

  • 输入：

    • path （字符串）

    • content （字符串）

• 编辑文件

  • 使用高级模式匹配和格式化进行选择性编辑

  • 输入：

    • path （字符串）

    • edits （ { oldText, newText }数组）

    • dryRun （布尔值，可选）

  • 特征：

    • 多行匹配

    • 缩进保存

    • Git 风格的差异预览

    • 非破坏性试运行模式

• 创建目录

  • 在 WSL 中创建目录或确保目录存在

  • 输入： path （字符串）

• 列表目录

  • 列出带有[FILE]或[DIR]前缀的目录内容

  • 输入： path （字符串）

• 目录树

  • 内容的递归 JSON 树视图

  • 输入： path （字符串）

• 移动文件

  • 移动或重命名文件/目录

  • 输入：

    • source （字符串）

    • destination （字符串）

• 搜索文件

  • 按名称递归搜索

  • 输入：

    • path （字符串）

    • pattern （字符串）

    • excludePatterns （字符串[]，可选）

• 获取文件信息

  • 详细元数据

  • 输入： path （字符串）

  • 返回：大小、时间戳、类型、权限

• 列出允许的目录

  • 列出服务器可访问的所有目录

• 列出 WSL 分布

  • 列出可用的发行版并显示活动的发行版

要求

• 正确配置Windows Subsystem for Linux (WSL)

• WSL 中至少安装了一个 Linux 发行版

对于 Claude Desktop 用户：
无需额外安装 - 只需配置您的claude_desktop_config.json 。

对于开发：

• Node.js （v14.0.0 或更高版本）

• TypeScript（作为开发依赖项包含）

在 Windows 上安装 Node.js

1. 从nodejs.org下载安装程序

2. 运行它并按照说明进行操作

3. 检查版本：

node --version
npm --version

用法

在运行服务器之前，您需要构建 TypeScript 项目：

npm install
npm run build

通过指定要使用的 WSL 发行版（可选）以及要公开的目录来运行服务器：

node dist/index.js [--distro=distribution_name] <allowed_directory> [additional_directories...]

如果没有指定分发，则将使用默认的 WSL 分发。

示例

访问 Ubuntu-20.04 发行版：

node dist/index.js --distro=Ubuntu-20.04 /home/user/documents

使用默认分布：

node dist/index.js /home/user/documents

与 Claude Desktop 一起使用

将其添加到您的claude_desktop_config.json中：

选项 1：使用特定的 WSL 发行版

{
  "mcpServers": {
    "wsl-filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-server-wsl-filesystem",
        "--distro=Ubuntu-20.04",
        "/home/user/documents"
      ]
    }
  }
}

选项 2：使用默认 WSL 发行版

{
  "mcpServers": {
    "wsl-filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-server-wsl-filesystem",
        "/home/user/documents"
      ]
    }
  }
}

在第二个示例中，系统将使用您的默认 WSL 发行版，而无需您指定它。

与原始项目的差异

此分支通过以下方式调整原始文件系统 MCP 服务器以与 WSL 配合使用：

1. 用 WSL 命令执行替换直接 Node.js 文件系统调用

2. 添加对选择特定 WSL 发行版的支持

3. 实现 Windows 和 Linux 格式之间的路径转换

4. 增强文件内容处理以实现跨平台兼容性

5. 添加用于 WSL 管理的专用工具

执照

该项目是模型上下文协议团队创建的原始文件系统 MCP 服务器的一个分支。

此 WSL 的 MCP 服务器遵循 MIT 许可证，并遵循原始项目的许可证。这意味着您可以自由使用、修改和分发该软件，但须遵守 MIT 许可证的条款和条件。有关更多详细信息，请参阅原始项目存储库中的 LICENSE 文件。