Filesystem MCP Server for WSL

⚠️重要信息：
原有的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

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

用法

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

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

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

示例

访问 Ubuntu-20.04 发行版：

使用默认分布：

与 Claude Desktop 一起使用

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

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

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

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

与原始项目的差异

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

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

执照

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

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