@modelcontextprotocol/server-wsl
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@modelcontextprotocol/server-wslShow me my WSL distributions"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 --installfrom 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)
Related MCP server: Linux Bash MCP Server
Installation
From npm (recommended)
npm install -g @modelcontextprotocol/server-wslFrom source
git clone https://github.com/modelcontextprotocol/servers.git
cd servers/src/wsl
npm install
npm run buildConfiguration
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 | Description |
| List all installed WSL distributions, their state (Running/Stopped), WSL version, and which is the default |
| Execute a bash command in a WSL distribution; returns stdout, stderr, and exit code |
| Read a text file from the WSL filesystem by absolute path |
| Write or overwrite a file in the WSL filesystem |
| List directory contents with names, types, permissions, sizes, and timestamps |
| Get detailed info about a distribution: WSL version, state, kernel, OS release, current user |
Tool parameters
run_command
Parameter | Type | Required | Description |
| string | ✅ | Bash command to run (passed to |
| string | Distribution name; defaults to your default distro | |
| number | Milliseconds before the command is killed; defaults to 30 000 |
read_file
Parameter | Type | Required | Description |
| string | ✅ | Absolute path within the WSL filesystem |
| string | Distribution name; defaults to your default distro |
write_file
Parameter | Type | Required | Description |
| string | ✅ | Absolute path within the WSL filesystem |
| string | ✅ | UTF-8 text content to write |
| string | Distribution name; defaults to your default distro |
list_directory
Parameter | Type | Required | Description |
| string | ✅ | Absolute path to the directory |
| string | Distribution name; defaults to your default distro |
get_distro_info
Parameter | Type | Required | Description |
| string | Distribution name; defaults to your default distro |
Example prompts
Once connected, try asking Claude:
"What WSL distributions do I have installed?"
"Run
df -hin my Ubuntu distro and show me disk usage""Read the file
/etc/hostsfrom WSL""Create a Python script at
/home/user/hello.pythat 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_msto 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
Available Tools
7 toolsget_distro_infoA
Get detailed information about a specific WSL distribution. Returns the WSL version, running state, current user identity, Linux kernel version, and OS release details (distro name, version, etc.). Useful for understanding the environment before running commands.
| Name | Required | Description | Default |
|---|---|---|---|
| distro | No | Name of the WSL distribution to inspect (e.g. 'Ubuntu', 'Debian'). Defaults to the system default distribution. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must fully convey behavioral traits. It describes the return data but does not disclose error behavior (e.g., when a distro does not exist), side effects (none expected), or permissions needed. Adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and key return fields. No unnecessary words; highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple info tool with no output schema, the description covers the returned fields adequately. It could be more complete by hinting at the output format or structure, but it is sufficient for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter already described. The description does not add further semantic value beyond what is in the schema, meeting the baseline for full coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves detailed information about a specific WSL distribution and lists the specific data returned (WSL version, state, etc.). It distinguishes from sibling 'list_distros' which lists all distributions, though not explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions 'useful for understanding the environment before running commands', implying usage context, but does not explicitly state when to use this tool versus siblings like 'list_distros' or 'run_command'. No exclusions or alternatives are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_directoryA
List the contents of a directory in the WSL filesystem. Returns each entry with its name, type (file, directory, symlink), Unix permissions, size in bytes, and last-modified timestamp. Equivalent to running ls -la in the target directory.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to the directory to list within the WSL filesystem, e.g. '/home/user' or '/var/log'. | |
| distro | No | Name of the WSL distribution. Defaults to the system default distribution. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the return format and that the operation is a read (like ls). It does not mention error handling or edge cases, but for a simple list operation, the transparency is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three efficient sentences with no wasted words. Front-loaded with the main purpose, followed by return details and a helpful analogy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity and full schema coverage, the description completely explains the tool's functionality and return values. No output schema is needed as the description covers return fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value by clarifying that 'path' must be absolute and 'distro' defaults to the system default distribution, providing contextual meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'list' and resource 'directory contents'. Provides specific return fields (name, type, permissions, size, timestamp) and an analogy to 'ls -la', distinguishing it from siblings like read_file and run_command.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The analogy to 'ls -la' strongly implies when to use this tool (listing directory contents) versus alternatives like run_command. However, it lacks explicit 'when not to use' guidance or comparisons to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_distrosA
List all installed WSL distributions and their current state. Shows each distribution's name, whether it is Running or Stopped, its WSL version (1 or 2), and which one is the default. Use this to discover available distributions before running commands.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the output details (name, status, version, default). No annotations present, but for a read-only list operation, the description is sufficiently transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundancies, efficiently conveys purpose and output.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequately explains output since no output schema is provided. Covers key elements but omits edge cases or error handling, acceptable for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so description does not need to add meaning. Baseline score of 4 applies per guidelines.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all installed WSL distributions with their state, distinguishing it from sibling tools like get_distro_info that focus on individual distros.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using this tool to discover available distributions before running commands, providing clear context. Could be improved by contrasting with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
read_fileA
Read the contents of a file from the WSL filesystem. Returns the file content as a UTF-8 string. Supports any text file accessible to the default WSL user. For binary files, consider piping through base64 using run_command instead.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to the file within the WSL filesystem, e.g. '/home/user/project/main.py' or '/etc/hosts'. | |
| distro | No | Name of the WSL distribution that contains the file. Defaults to the system default distribution. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses return format (UTF-8 string), accessibility constraints, and suggests alternative for binary files. Lacks details on error behavior, size limits, or encoding issues, but covers core traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, then return format, then a usage tip. No wasted words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 2 parameters and no output schema, the description covers return type, a key constraint (user accessibility), and an important edge case (binary files). Slightly lacking on error conditions, but adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds example for path but does not enrich distro parameter beyond the existing schema description. Minimal added value over schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads file contents from the WSL filesystem, specifying the resource and action. It distinguishes from sibling tools like write_file and run_command by focusing on reading text files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance for binary files (use run_command with base64) and mentions accessibility by default WSL user, offering context for when to use. Does not fully exclude other scenarios but gives a clear alternative for a common edge case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
run_commandA
Execute a shell command inside a WSL distribution as the default (unprivileged) user. Returns stdout, stderr, and the exit code. Do NOT include 'sudo' in the command — it will hang waiting for a password that cannot be supplied. For operations that require root access use run_privileged_command instead.
| Name | Required | Description | Default |
|---|---|---|---|
| distro | No | Name of the WSL distribution to run the command in (e.g. 'Ubuntu', 'Debian'). Defaults to the system default distribution. | |
| command | Yes | The bash command to execute (passed to `bash -c`). Must not contain 'sudo'. Complex commands with pipes, redirections, and multi-line scripts are all supported. | |
| timeout_ms | No | Maximum execution time in milliseconds before the command is killed. Defaults to 30000 (30 seconds). Increase for long-running operations. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description fully discloses behavior: runs as unprivileged user, returns stdout/stderr/exit code, uses bash -c, supports complex commands, has configurable timeout, and warns about sudo hanging. This is comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each with a clear function: purpose+output, sudo warning, alternative, and no extra fluff. Highly efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple execution tool with no output schema, the description covers key aspects: intent, return values, limitations, and timeout. Minor omission of error handling beyond exit code, but still complete enough for agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 3 parameters with detailed descriptions (100% coverage). The description mostly reiterates schema content; it adds slight context about supporting complex commands and timeout usage, but baseline is 3 per guidelines.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Execute a shell command inside a WSL distribution' with specific verb and resource. Distinguishes from sibling run_privileged_command by specifying 'unprivileged user' and explicitly warns against using sudo, which differentiates its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool vs. alternatives: 'Do NOT include sudo... For operations that require root access use run_privileged_command instead.' This provides clear context for selecting the right tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
run_privileged_commandA
⚠️ ELEVATED — runs as root (via wsl.exe --user root). IMPORTANT: Before calling this tool you MUST show the user the exact command that will be executed and ask for explicit confirmation. Only call it once the user has confirmed. Use this instead of sudo — do not include 'sudo' in the command string. Examples of operations that require this tool: apt install, systemctl, editing /etc files, chown/chmod on system paths, mounting filesystems.
| Name | Required | Description | Default |
|---|---|---|---|
| distro | No | Name of the WSL distribution. Defaults to the system default distribution. | |
| reason | No | Brief explanation of why root access is needed, shown alongside the confirmation prompt. E.g. 'install nginx via apt' or 'edit /etc/hosts'. | |
| command | Yes | The bash command to run as root (passed to `bash -c`). Do not prefix with 'sudo' — the command already runs as root. | |
| timeout_ms | No | Maximum execution time in milliseconds. Defaults to 30000 (30 seconds). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses elevation, required user confirmation, and behavioral constraints (no sudo). Lacks details on error handling or reversibility, but is substantially transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is short and front-loaded with critical warnings and instructions. Every sentence is necessary, though examples could be separated for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 4 parameters with full schema descriptions, the tool description adequately covers the privileged execution context, required user interaction flow, and usage examples. Minor gap: no mention of failure behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds context about command being passed to bash -c and default timeout, but minimally enhances parameter meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs as root via wsl.exe --user root, distinguishing it from run_command which likely runs as normal user. The verb 'runs' and resource 'root' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit instructions: must show user the exact command and get confirmation before calling. Also states to use instead of sudo, and provides examples of appropriate operations (apt install, systemctl, etc.).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
write_fileA
Write or overwrite a file in the WSL filesystem with the provided content. Creates the file if it does not exist; overwrites it if it does. The parent directory must already exist. Use run_command with mkdir -p to create missing directories first.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path where the file should be written within the WSL filesystem, e.g. '/home/user/project/script.sh'. | |
| distro | No | Name of the WSL distribution. Defaults to the system default distribution. | |
| content | Yes | The UTF-8 text content to write to the file. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the tool creates or overwrites files, requires an existing parent directory, and writes UTF-8 text. It does not cover error cases like permissions or disk space, but for a file write tool the core behaviors are transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the primary action, the second provides a precondition and alternative. Every sentence adds value without unnecessary text. The critical information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 params, no output schema), the description covers the main purpose, preconditions, and usage context. It mentions the WSL filesystem and UTF-8 encoding. Minor gaps: no mention of return value or error handling, but adequate for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage with descriptions for all three parameters. The description adds value by specifying that the path must be absolute within the WSL filesystem and that content is UTF-8 text, and reiterates the parent directory constraint.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Write or overwrite' and the resource 'file in the WSL filesystem'. It distinguishes from siblings by specifying writing versus reading (read_file) or command execution (run_command). The create/overwrite behavior is explicitly noted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use (writing files), a key prerequisite (parent directory must exist), and a direct alternative ('Use run_command with mkdir -p to create missing directories first'). This offers clear guidance for proper invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
7 tool updates
v0.1.0- First observed
get_distro_info - First observed
list_directory - First observed
list_distros - First observed
read_file - First observed
run_command - First observed
run_privileged_command - First observed
write_file
TDQS
Scored across 7 tools
Each tool has a clear, distinct purpose. File operations, command execution, and distro management tools are clearly separated with no overlap.
All tool names follow a consistent verb_noun pattern with snake_case (e.g., read_file, list_distros, run_privileged_command). No mixing of conventions.
7 tools is a well-scoped set for managing WSL: file operations, command execution (normal and privileged), and distro discovery/inspection. Not too few or too many.
Covers essential WSL operations (file management, command execution, distro info). Minor missing operations like starting/stopping distros or managing defaults, but these are less critical for typical workflows.
Maintenance
Related MCP Connectors
Share context and questions between Claude instances — VS Code, claude.ai web, and mobile.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Deploy, monitor, and manage your OpenClaw AI assistants via natural language.
- platform7nOAuthtech.p7n
Connect Claude to your Platform7n workspaces — chat, links, and tasks. One-click OAuth.
Related MCP Servers
- AlicenseAqualityFmaintenanceEnables Claude Desktop to interact with and view tmux session content, allowing AI assistants to read from, control, and observe terminal sessions.13211 npm301MIT
- AlicenseAqualityDmaintenanceA Model Context Protocol server that enables Claude Desktop to execute bash commands and scripts in WSL2 Linux distributions on Windows.6MIT
- FlicenseNot gradedqualityNot gradedmaintenanceAdds automation capabilities to Claude Desktop through MCP and enables Claude Desktop to act as a model gateway for Claude Code, solving WSL-Windows integration challenges through file-based bidirectional communication.-
- AlicenseBqualityDmaintenanceEnables Claude Desktop to interact with 57 AWS services using over 200 tools and local machine profiles. It supports multi-profile configurations and features a read-only safe mode by default to manage infrastructure like EC2, S3, and Lambda securely.100BSD 3-Clause