mcp -wsl-filesystem

This MCP server provides a specialized filesystem interface for Windows Subsystem for Linux (WSL). It exposes WSL directories to the MCP ecosystem and enables fast, Linux-native operations inside WSL by leveraging native commands rather than walking the filesystem with Node.js. You can list directories, read and write files, create and delete directories, move items, and perform fast content searches within the configured WSL distributions. The server exposes a set of tools that mirror common filesystem operations (read_file, read_file_by_parts, read_multiple_files, write_file, edit_file, create_directory, list_directory, directory_tree, move_file, search_files, search_in_files, get_file_info, list_allowed_directories, list_wsl_distributions) and is optimized for WSL environments, allowing you to work with Windows-hosted access to Linux files efficiently.

To use it, start the MCP server with the appropriate distribution and the directories you want to expose. For Claude Desktop users, you can add it to your claude_desktop_config.json to integrate the server into your workflow. The provided example runs the WSL filesystem server against a specific distro (Ubuntu-20.04) and exposes /home/user/documents. You can adjust the distro and paths as needed to fit your environment.

Prerequisites:

• Node.js (v18.0.0 or higher) and npm
• A working WSL setup with at least one Linux distribution installed

Installation steps:

1. Install dependencies and build the project

npm install
npm run build

2. Run the server (example)

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

3. Verify the server starts and is reachable via MCP clients. If you plan to package or deploy via npm, ensure the npm package name is used consistently (see npm_package field).

Note: The repository is designed to work both with Claude Desktop and standalone MCP clients. If you use the Claude Desktop integration, you can place a config in claude_desktop_config.json that references the npm package (mcp-server-wsl-filesystem) and pass distro/path arguments accordingly.

Tips and considerations:

• The server is designed to restrict operations to directories explicitly exposed in the configuration (args). Always limit exposure to just the needed WSL paths.
• When using search_in_files or read_file_by_parts, the performance benefits come from leveraging native WSL/Linux commands inside the distribution; ensure your distribution supports the required tools (find, grep, etc.).
• The CLI usage in README shows how to specify a distro with --distro; omit it to use the default WSL distribution.
• Common issues often relate to permissions or paths mismatching between Windows and WSL. Use absolute Linux paths (e.g., /home/username/...) for best results.
• To add more directories, pass additional path arguments to the server start command.
• If integrating with Claude Desktop, keep the distro and path values aligned with your actual WSL setup to avoid misconfigurations.