Filesystem MCP Server for WSL

⚠️ 重要信息：
原始的 Filesystem MCP Server 已经可以访问 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 的 Filesystem MCP Server

这是一个使用 Node.js 实现的 MCP 服务，专为 Windows Subsystem for Linux（WSL）中的文件系统操作而设计。
本项目是原始 Filesystem MCP Server 的分支，但针对 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 等）
  • 功能：
    • 第 1 部分从文件开头开始
    • 后续部分与行边界对齐（最多调整 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

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

---

要求

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

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 发行版，无需手动指定。

与原项目的区别

此分支对原始 Filesystem MCP Server 进行了调整，使其能够与 WSL 配合使用，具体包括：

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

许可证

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

此 WSL MCP 服务采用 MIT 许可证，遵循原项目的许可证。这意味着你可以自由使用、修改和分发该软件，但须遵守 MIT 许可证的条款和条件。详情请参阅原项目仓库中的 LICENSE 文件。