Integrations
Enables seamless interaction with Linux distributions under WSL, providing tools to access, manipulate, and search the Linux filesystem from Windows.
Implements file operations through Node.js for WSL environments, enabling read/write, directory management, and file search capabilities.
Built with TypeScript, requiring it as a development dependency for building the project from source.
⚠️ IMPORTANT INFORMATION:
The original Filesystem MCP Server can already access WSL files by simply using the network path\\wsl.localhost\DistributionName
as a parameter in the configuration.
Example:CopyHowever, this project offers an alternative implementation specifically optimized for WSL Linux distributions.
While the official server works by recursively walking directories using Node.js’s
fs
module, this implementation leverages native Linux commands inside WSL (such asfind
,grep
, etc.), making file listing and content search operations significantly faster.This can be especially useful when dealing with large directory trees or when search performance is critical.
So while the native network path may be simpler for many use cases, this project remains a valuable solution for WSL users looking for better performance or more custom control over the indexing and searching logic.
Filesystem MCP Server for WSL
Node.js server implementing the Model Context Protocol (MCP), specifically designed for filesystem operations in Windows Subsystem for Linux (WSL).
This project is a fork of the original Filesystem MCP Server but completely reimagined for WSL environments.
Unlike the original project, which handles generic file operations, this version focuses exclusively on seamless interaction between Windows and Linux distributions under WSL.
Both projects are compatible and can run in parallel on the same system.
Features
- Access any WSL distribution from Windows
- Read/write files in WSL from Windows host
- Create/list/delete directories in WSL
- Move files/directories across WSL filesystem
- Search files within WSL
- Get file metadata from the WSL filesystem
- Support for multiple WSL distributions
Note: The server only allows operations within directories specified via args
.
API
Resources
wsl -d <distrib>
: Command for operations on WSL distributions
Tools
- read_file
- Read complete contents of a file from WSL
- Input:
path
(string) - Reads content as UTF-8 text
- read_multiple_files
- Read multiple files simultaneously from WSL
- Input:
paths
(string[]) - Failed reads won't stop the entire operation
- write_file
- Create or overwrite a file in WSL (use with caution)
- Inputs:
path
(string)content
(string)
- edit_file
- Selective edits with advanced pattern matching and formatting
- Inputs:
path
(string)edits
(array of{ oldText, newText }
)dryRun
(boolean, optional)
- Features:
- Multi-line matching
- Indentation preservation
- Git-style diff preview
- Non-destructive dry run mode
- create_directory
- Create or ensure the existence of a directory in WSL
- Input:
path
(string)
- list_directory
- List directory contents with
[FILE]
or[DIR]
prefixes - Input:
path
(string)
- List directory contents with
- directory_tree
- Recursive JSON tree view of contents
- Input:
path
(string)
- move_file
- Move or rename files/directories
- Inputs:
source
(string)destination
(string)
- search_files
- Recursively search by name
- Inputs:
path
(string)pattern
(string)excludePatterns
(string[], optional)
- get_file_info
- Detailed metadata
- Input:
path
(string) - Returns: size, timestamps, type, permissions
- list_allowed_directories
- Lists all directories accessible to the server
- list_wsl_distributions
- Lists available distributions and shows the active one
Requirements
- Windows Subsystem for Linux (WSL) properly configured
- At least one Linux distribution installed in WSL
For Claude Desktop users:
No additional installation required — just configure your claude_desktop_config.json
.
For development:
- Node.js (v14.0.0 or higher)
- TypeScript (included as a dev dependency)
Installing Node.js on Windows
- Download the installer from nodejs.org
- Run it and follow the instructions
- Check versions:
Usage
Before running the server, you need to build the TypeScript project:
Run the server by specifying which WSL distribution to use (optional) and which directories to expose:
If no distribution is specified, the default WSL distribution will be used.
Examples
Access Ubuntu-20.04 distribution:
Use default distribution:
Usage with Claude Desktop
Add this to your claude_desktop_config.json
:
Option 1: Using a specific WSL distribution
Option 2: Using the default WSL distribution
In the second example, the system will use your default WSL distribution without you needing to specify it.
Differences from original project
This fork adapts the original Filesystem MCP Server to work with WSL by:
- Replacing direct Node.js filesystem calls with WSL command executions
- Adding support for selecting specific WSL distributions
- Implementing path translation between Windows and Linux formats
- Enhancing file content handling for cross-platform compatibility
- Adding specialized tools for WSL management
License
This project is a fork of the original Filesystem MCP Server created by the Model Context Protocol team.
This MCP server for WSL is licensed under the MIT License, following the original project's license. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the original project repository.
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
Node.js server implementing Model Context Protocol that enables seamless interaction between Windows and Linux distributions under WSL, allowing file operations like reading, writing, searching, and managing files across the WSL filesystem from Windows.
Related MCP Servers
- -securityAlicense-qualityNode.js server implementing Model Context Protocol (MCP) for filesystem operations.Last updated -29,12443,205JavaScriptMIT License
- -securityFlicense-qualityNode.js server implementing Model Context Protocol for filesystem operations, allowing Claude to read, write, and manipulate files and directories in specified locations.Last updated -29,124JavaScript
- -securityFlicense-qualityA Node.js application that provides a Model Context Protocol server for interacting with Harbor container registry, supporting operations for projects, repositories, tags, and Helm charts.Last updated -TypeScript
- -securityAlicense-qualityNode.js server implementing Model Context Protocol for secure read-only filesystem operations, allowing Claude to read files, list directories, search files, and get file metadata within specified directories.Last updated -91JavaScriptMIT License