WSL 的文件系统 MCP 服务器

⚠️重要信息：
原有的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指定的目录内进行操作。

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

从nodejs.org下载安装程序
运行它并按照说明进行操作
检查版本：

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 配合使用：

用 WSL 命令执行替换直接 Node.js 文件系统调用
添加对选择特定 WSL 发行版的支持
实现 Windows 和 Linux 格式之间的路径转换
增强文件内容处理以实现跨平台兼容性
添加用于 WSL 管理的专用工具

执照

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

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

Filesystem MCP Server for WSL

Integrations