WSL Filesystem MCP Server

How to use

Use this MCP server with your MCP client to access and manage files inside WSL distributions. You can point the server at one or more allowed directories and, if needed, specify a particular WSL distribution. The server handles operations such as reading file contents, listing directories, creating and moving files, and performing searches inside WSL.

How to install

Prerequisites you need before installing:
- Windows with WSL configured and at least one Linux distribution installed
- Node.js v18.x or higher installed on Windows
- npm (comes with Node.js) or npx available for package execution
- Git (optional, for cloning a repository if you prefer)

Install the package locally and build the TypeScript sources, then run the server from the built artifacts.

# Install dependencies and build
npm install
npm run build

# Run the server for a specific distribution (example)
node dist/index.js --distro=Ubuntu-20.04 /home/user/documents

Additional configuration and usage notes

Configure how you run the server from your MCP client. You can expose a single allowed directory or multiple directories, and you may choose to target a specific WSL distribution or use the default one.

If you prefer using a modern MCP client configuration, you can run the server via a package runner, such as npx, and point it at the built distribution with the appropriate arguments.

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

Troubleshooting and tips

If you encounter issues connecting to WSL or accessing directories, verify that the specified paths exist in the WSL environment and that the distribution name matches one of your installed WSL distributions. Ensure your Windows user has appropriate permissions for the WSL paths you expose. If a distribution is not specified, the server will use the default WSL distribution.

Notes

The server supports multiple WSL distributions and can be run alongside other MCP servers on the same system. Remember to only expose directories that you want Windows clients to access, and exercise caution with write permissions.

read_file

Read complete contents of a file inside WSL; input is a path and the content is returned as UTF-8 text.

read_file_by_parts

Read large files in parts of approximately 95,000 characters. Supports part navigation and returns the actual file size if a requested part does not exist.

read_multiple_files

Read multiple files in parallel from WSL; non-fatal failures are reported per-file without aborting the entire operation.

write_file

Create or overwrite a file inside WSL. Use with caution.

edit_file

Perform selective edits with pattern matching, including multi-line matches and indentation preservation. Supports a dry-run mode and a Git-like diff preview.

create_directory

Create or ensure the existence of a directory in WSL.

list_directory

List directory contents with [FILE] or [DIR] prefixes.

directory_tree

Provide a recursive JSON tree view of a directory's contents.

move_file

Move or rename files or directories within the WSL filesystem.

search_files

Recursively search for items by name inside a path, supporting include/exclude patterns.

search_in_files

Recursively search for text patterns inside files, with options for case, regex, includes/excludes, and result context.

get_file_info

Return detailed metadata for a given path, including size, timestamps, type, and permissions.

list_allowed_directories

List all directories that are accessible to the server.

list_wsl_distributions

List available WSL distributions and indicate the active one.