Filesystem MCP Server for WSL

A filesystem server for Windows Subsystem for Linux (WSL), using native commands for faster file operations.

⚠️IMPORTANT INFORMATION:
The originalFilesystem MCP Servercan already access WSL files by simply using the network path\\wsl.localhost\DistributionNameas a parameter in the configuration.
Example:

{ "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "\\\\wsl.localhost\\Debian", "C:\\path\\to\\other\\allowed\\dir" ] } } }

However, this project offers analternative implementation specifically optimized for WSL Linux distributions.

While the official server works by recursively walking directories using Node.js’sfsmodule, this implementation leveragesnative Linux commands inside WSL(such asfind,grep, etc.), makingfile 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 remainsa valuable solutionfor WSL users looking forbetter performanceor morecustom controlover the indexing and searching logic.

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 originalFilesystem MCP Serverbut 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.

- Read multiple files simultaneously from WSL
- Input:paths(string[])
- Failed reads won't stop the entire operation

- Create or overwrite a file in WSL (use with caution)
- Inputs:

- path(string)
- content(string)

- Selective edits with advanced pattern matching and formatting
- Inputs:

- path(string)
- edits(array of{ oldText, newText })
- dryRun(boolean, optional)

- Multi-line matching
- Indentation preservation
- Git-style diff preview
- Non-destructive dry run mode

- Create or ensure the existence of a directory in WSL
- Input:path(string)

- List directory contents with[FILE]or[DIR]prefixes
- Input:path(string)

- Recursive JSON tree view of contents
- Input:path(string)

- Move or rename files/directories
- Inputs:

- source(string)
- destination(string)

- Recursively search by name
- Inputs:

- path(string)
- pattern(string)
- excludePatterns(string[], optional)

- Search for text patterns within files recursively
- Inputs:

- path(string) - root directory to search
- pattern(string) - text or regex pattern to find
- caseInsensitive(boolean, optional) - case-insensitive search
- isRegex(boolean, optional) - treat pattern as regex
- includePatterns(string[], optional) - file patterns to include (e.g., *.js)
- excludePatterns(string[], optional) - file patterns to exclude
- maxResults(number, optional, default: 1000) - maximum results to return
- contextLines(number, optional, default: 0) - lines of context before/after

- Handles all special characters (apostrophes, quotes, $, backslashes)
- Supports plain text and regular expression searches
- Shows matching lines with file paths and line numbers
- Automatically excludes .git, node_modules, .svn, .hg directories
- Can show context lines around matches

- Detailed metadata
- Input:path(string)
- Returns: size, timestamps, type, permissions

- Lists all directories accessible to the server

- Lists available distributions and shows the active one

- Windows Subsystem for Linux (WSL)properly configured
- At least one Linux distribution installed in WSL

NPM Package:
The package is available on npm:mcp-server-wsl-filesystem

- Node.js(v18.0.0 or higher)
- TypeScript (included as a dev dependency)
- Download the installer fromnodejs.org
- Run it and follow the instructions
- Check versions:

node dist/index.js [--distro=distribution_name] <allowed_directory> [additional_directories...]

If no distribution is specified, the default WSL distribution will be used.

node dist/index.js --distro=Ubuntu-20.04 /home/user/documents

Add this to yourclaude_desktop_config.json:

Option 1: Using a specific WSL distribution

{ "mcpServers": { "wsl-filesystem": { "command": "npx", "args": [ "-y", "mcp-server-wsl-filesystem", "--distro=Ubuntu-20.04", "/home/user/documents" ] } } }

Option 2: Using the default WSL distribution

{ "mcpServers": { "wsl-filesystem": { "command": "npx", "args": [ "-y", "mcp-server-wsl-filesystem", "/home/user/documents" ] } } }

In the second example, the system will use your default WSL distribution without you needing to specify it.

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

This project is a fork of the originalFilesystem MCP Servercreated by the Model Context Protocol team.

A secure server for filesystem operations with controlled access to specified directories.