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

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

该项目仍然可用于特定用例，并作为替代实现的示例，但对于大多数用户来说，使用带有原生网络路径的原始 MCP 服务器可能更简单。

针对 WSL 的 Filesystem MCP 服务器

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

特性

• 从 Windows 访问任何 WSL 发行版
• 在 WSL 中从 Windows 主机读写文件
• 在 WSL 中创建/列出/删除目录
• 在 WSL 文件系统中移动文件/目录
• 在 WSL 中搜索文件
• 从 WSL 文件系统获取文件元数据
• 支持多个 WSL 发行版

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

API

资源

• wsl -d <distrib>: 对 WSL 发行版进行操作的命令

工具

• read_file

  • 从 WSL 读取文件的全部内容
  • 输入: path (字符串)
  • 使用 UTF-8 编码读取文件的全部内容

• read_multiple_files

  • 从 WSL 同时读取多个文件
  • 输入: paths (字符串数组)
  • 失败的读取不会停止整个操作

• write_file

  • 在 WSL 中创建新文件或覆盖现有文件（请谨慎使用）
  • 输入:
    • path (字符串): 文件位置
    • content (字符串): 文件内容

• edit_file

  • 使用高级模式匹配和格式化在 WSL 文件中进行选择性编辑
  • 功能:
    • 基于行和多行内容匹配
    • 保留缩进的空白字符规范化
    • 正确定位的多次同时编辑
    • 检测并保留缩进样式
    • 带有上下文的 Git 风格差异输出
    • 通过干运行模式预览更改
  • 输入:
    • path (字符串): 要编辑的文件
    • edits (数组): 编辑操作列表
      • oldText (字符串): 要搜索的文本（可以是子字符串）
      • newText (字符串): 要替换为的文本
    • dryRun (布尔值): 预览更改而不应用（默认：false）
  • 返回详细的差异和匹配信息用于干运行，否则应用更改

• create_directory

  • 在 WSL 中创建新目录或确保其存在
  • 输入: path (字符串)
  • 如果需要，将创建父目录
  • 如果目录已存在，则静默成功

• list_directory

  • 列出 WSL 目录的内容，并带有 [FILE] 或 [DIR] 前缀
  • 输入: path (字符串)

• directory_tree

  • 以 JSON 结构获取文件和目录的递归树视图
  • 输入: path (字符串)
  • 返回具有名称、类型和子项属性的树结构

• move_file

  • 在 WSL 中移动或重命名文件和目录
  • 输入:
    • source (字符串)
    • destination (字符串)
  • 如果目标已存在则失败

• search_files

  • 在 WSL 中递归搜索文件/目录
  • 输入:
    • path (字符串): 起始目录
    • pattern (字符串): 搜索模式
    • excludePatterns (字符串数组): 排除任何模式。支持 Glob 格式。
  • 不区分大小写的匹配
  • 返回匹配项的完整路径

• get_file_info

  • 从 WSL 获取文件/目录的详细元数据
  • 输入: path (字符串)
  • 返回:
    • 大小
    • 创建时间
    • 修改时间
    • 访问时间
    • 类型（文件/目录）
    • 权限

• list_allowed_directories

  • 列出服务器在 WSL 中允许访问的所有目录
  • 无需输入

• list_wsl_distributions

  • 列出所有可用的 WSL 发行版，并显示当前正在使用的发行版
  • 无需输入

要求

• Windows Subsystem for Linux (WSL) 已正确配置
• 至少安装了一个 WSL 中的 Linux 发行版

对于 Claude Desktop 用户：无需额外安装

对于开发：

• Node.js (v14.0.0 或更高版本)
• TypeScript（作为开发依赖安装）

在 Windows 上安装 Node.js

1. 从 官方 Node.js 网站 下载 Windows 安装程序
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 管理的工具

许可证

该项目是原始 Filesystem MCP Server 的一个分支，由 Model Context Protocol 团队创建。

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