AI导哈

WSL文件系统服务器

一个专为Windows Subsystem for Linux (WSL)设计的文件系统服务器，提供高性能的文件操作和搜索功能。

  • by webconsulting
  • JavaScript
  • 本地部署
  • 16 星标
  • 更新于
在 GitHub 查看 webconsulting/mcp-server-wsl-filesystem

使用说明

⚠️ 重要信息：
原版 文件系统MCP服务器 只需使用网络路径即可访问WSL文件 \\wsl.localhost\DistributionName 作为配置中的参数。
例子：

{
  "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服务器

实现模型上下文协议（MCP）的Node.js服务器，专为Windows Linux子系统（WSL）中的文件系统操作而设计。
这个项目是原始项目的一个分支 文件系统MCP服务器 但完全针对WSL环境进行了重新设计。
与处理通用文件操作的原始项目不同，此版本专门关注WSL下Windows和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

    • 读取约95000个字符的大文件
    • 输入：
      • path （字符串）
      • part_number （正整数：1、2、3等）
    • 特征：
      • 第1部分从文件的开头开始
      • 后续零件与线边界对齐（最多300个字符的调整）
      • 如果请求的部件不存在，则返回实际文件大小的错误
      • 适用于太大而无法在一次操作中读取的文件

  • 读取多个文件

    • 从WSL同时读取多个文件
    • 输入： paths （字符串[]）
    • 读取失败不会停止整个操作

  • write_file

    • 在WSL中创建或覆盖文件（小心使用）
    • 输入：
      • path （字符串）
      • content （字符串）

  • edit_file

    • 通过高级模式匹配和格式化进行选择性编辑
    • 输入：
      • path （字符串）
      • edits （数组 { oldText, newText })
      • dryRun （布尔值，可选）
    • 特征：
      • 多线匹配
      • 压痕保存
      • Git风格差异预览
      • 无损干运行模式

  • create_directory

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

  • list_directory

    • 列出目录内容 [FILE] 或 [DIR] 前缀
    • 输入： path （字符串）

  • 目录树

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

  • move_file

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

  • 搜索文件

    • 按名称递归搜索
    • 输入：
      • path （字符串）
      • pattern （字符串）
      • excludePatterns （string[]，可选）

  • search_in_files

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

  • 获取_文件_信息

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

  • list_allowed_directories

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

  • list_wsl_分布

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

需求

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

NPM包：
该包可以在npm上找到： mcp服务器wsl文件系统

发展：

  • 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管理专用工具

许可证

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

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

相关 MCP