⚠️ 重要信息：\ 原版 文件系统MCP服务器 只需使用网络路径即可访问WSL文件\\wsl.localhost\DistributionName作为配置中的参数。\ 例子： ``json { "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：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_分布
- 列出可用的发行版并显示活动发行版
______________________________________________________________________
需求
- Windows Linux子系统（WSL） 正确配置
- WSL中至少安装了一个Linux发行版
对于Claude Desktop用户：\ 无需额外安装，只需配置您的 claude_desktop_config.json.
NPM包：\ 该包可以在npm上找到： mcp服务器wsl文件系统
发展：
- （v18.0.0或更高版本）
- TypeScript（作为开发依赖项包含在内）
在Windows上安装Node.js
- 从下载安装程序
- 运行它并按照说明操作
- 检查版本：
node --version
npm --version用法
在运行服务器之前，您需要构建TypeScript项目：
npm install
npm run build通过指定要使用的WSL发行版（可选）和要公开的目录来运行服务器：
node dist/index.js [--distro=distribution_name] [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：
- 用WSL命令执行替换直接的Node.js文件系统调用
- 添加对选择特定WSL发行版的支持
- 实现Windows和Linux格式之间的路径转换
- 增强文件内容处理以实现跨平台兼容性
- 添加WSL管理专用工具
许可证
这个项目是原始项目的一个分支 文件系统MCP服务器 由模型上下文协议团队创建。
WSL的此MCP服务器遵循原始项目的许可证，根据MIT许可证获得许可。这意味着您可以根据MIT许可证的条款和条件自由使用、修改和分发软件。有关更多详细信息，请参阅原始项目存储库中的LICENSE文件。