Local Opsecured Build:

Independent Build:

@modelcontextprotocol/server-wsl

An MCP server that gives Claude Desktop full access to your Windows Subsystem for Linux (WSL) environment. Run commands, read and write files, and inspect your distributions — all from a Claude conversation on Windows.

Prerequisites

• Windows 10 version 2004+ or Windows 11

• WSL 2 installed (wsl --install from an admin PowerShell)

• At least one Linux distribution installed via the Microsoft Store or wsl --install -d <Distro>

• Node.js 18 or later (for building from source)

Installation

From npm (recommended)

npm install -g @modelcontextprotocol/server-wsl

From source

git clone https://github.com/modelcontextprotocol/servers.git
cd servers/src/wsl
npm install
npm run build

Configuration

Add the server to your Claude Desktop configuration file.

Config file location:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Using npx (zero-install)

{
  "mcpServers": {
    "wsl": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-wsl"]
    }
  }
}

Using a globally installed package

{
  "mcpServers": {
    "wsl": {
      "command": "mcp-server-wsl"
    }
  }
}

Running via WSL itself (alternative)

If you prefer to run the server inside WSL, you can invoke it through wsl.exe:

{
  "mcpServers": {
    "wsl": {
      "command": "wsl.exe",
      "args": ["node", "/path/to/wsl-mcp/dist/index.js"]
    }
  }
}

After editing the config, restart Claude Desktop. You should see the WSL tools appear in the Claude tool picker.

Available Tools

Tool parameters

run_command

read_file

write_file

list_directory

get_distro_info

Example prompts

Once connected, try asking Claude:

• "What WSL distributions do I have installed?"

• "Run df -h in my Ubuntu distro and show me disk usage"

• "Read the file /etc/hosts from WSL"

• "Create a Python script at /home/user/hello.py that prints Hello, World"

• "List what's in my home directory in WSL"

• "What kernel version is my WSL instance running?"

Security considerations

• Commands execute as the default user of the chosen distribution (typically your regular Linux user, not root).

• There is no path sandboxing — Claude can read and write any file the WSL user has access to. Grant this MCP server only to trusted Claude conversations.

• Command output is capped at 10 MB to prevent runaway processes from overwhelming the host.

• The default command timeout is 30 seconds; use timeout_ms to increase it for long-running tasks.

Troubleshooting

"wsl.exe not found" WSL is not installed or not on the system PATH. Run wsl --install from an admin PowerShell.

"No default WSL distribution is configured" You have WSL installed but no distribution set as default. Fix with: wsl --set-default <DistroName>

Distribution shows as Stopped but commands still work This is expected — WSL automatically starts a stopped distribution when a command is run.

UTF-8 output looks garbled Some older Windows builds emit WSL list output as UTF-16 LE. The server normalises this automatically; if you still see issues, ensure your WSL is up to date (wsl --update).

License

MIT