STARWARCLOUD STARWAR.AI
返回市场
MCP服务器-WSL文件系统

MCP服务器-WSL文件系统

作者：webconsulting8 星标更新：2025-08-30
安装使用来源：spider==github.com

项目介绍

【技术文档摘要】：

⚠️ 重要信息：
原始的 文件系统 MCP 服务器 可以通过在配置中使用网络路径 \\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 服务器

npm 版本 许可证: MIT

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

功能

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

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

API

资源

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

工具

  • read_file

    • 从 WSL 读取文件的全部内容
    • 输入：path (字符串)
    • 以 UTF-8 文本形式读取内容

  • read_file_by_parts

    • 分段读取大约 95,000 字符的大文件
    • 输入：
      • path (字符串)
      • part_number (正整数：1, 2, 3 等)
    • 特性：
      • 第一部分从文件开头开始
      • 后续部分对齐到行边界（最多 300 字符调整）
      • 如果请求的部分不存在，则返回实际文件大小的错误
      • 对于太大而无法一次性读取的文件很有用

  • read_multiple_files

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

  • write_file

    • 在 WSL 中创建或覆盖文件（谨慎使用）
    • 输入：
      • path (字符串)
      • content (字符串)

  • edit_file

    • 使用高级模式匹配和格式化进行选择性编辑
    • 输入：
      • path (字符串)
      • edits (对象数组：{ oldText, newText })
      • dryRun (布尔值，可选)
    • 特性：
      • 多行匹配
      • 保留缩进
      • 类似 Git 的差异预览
      • 非破坏性的干运行模式

  • create_directory

    • 在 WSL 中创建或确保目录的存在
    • 输入：path (字符串)

  • list_directory

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

  • directory_tree

    • 递归的 JSON 树视图内容
    • 输入：path (字符串)

  • move_file

    • 移动或重命名文件/目录
    • 输入：
      • source (字符串)
      • destination (字符串)

  • search_files

    • 递归按名称搜索
    • 输入：
      • path (字符串)
      • pattern (字符串)
      • excludePatterns (字符串数组，可选)

  • search_in_files

    • 递归搜索文件中的文本模式
    • 输入：
      • path (字符串) - 搜索的根目录
      • pattern (字符串) - 要查找的文本或正则表达式模式
      • caseInsensitive (布尔值，可选) - 不区分大小写的搜索
      • isRegex (布尔值，可选) - 将模式视为正则表达式
      • includePatterns (字符串数组，可选) - 包含的文件模式（例如，*.js）
      • excludePatterns (字符串数组，可选) - 排除的文件模式
      • maxResults (数字，可选，默认值：1000) - 返回的最大结果数
      • contextLines (数字，可选，默认值：0) - 匹配前后显示的上下文行数
    • 特性：
      • 处理所有特殊字符（撇号、引号、$、反斜杠）
      • 支持纯文本和正则表达式搜索
      • 显示带有文件路径和行号的匹配行
      • 自动排除 .git、node_modules、.svn、.hg 目录
      • 可以显示匹配周围的上下文行

  • get_file_info

    • 详细的元数据
    • 输入：path (字符串)
    • 返回：大小、时间戳、类型、权限

  • list_allowed_directories

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

  • list_wsl_distributions

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

要求

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

NPM 包：
该包可在 npm 上找到：mcp-server-wsl-filesystem

对于开发：

  • Node.js (v18.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 管理的工具

许可证

此项目是 Model Context Protocol 团队创建的原始 文件系统 MCP 服务器 的分支。

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