mcp-wsl-exec

A Model Context Protocol (MCP) server for **Windows + Claude Desktop

users** to interact with Windows Subsystem for Linux (WSL). Provides

both read-only information gathering and secure command execution

capabilities.

⚠️ Important: Who Should Use This?

✅ You SHOULD use this if:

• You're using Claude Desktop on Windows
• You need to interact with your WSL environment
• You want to provide WSL context to Claude (system info, processes,

files, etc.)

❌ You DON'T need this if:

• You're using Claude Code (it has native bash access)
• You're on Linux/macOS (use native tools instead)
• You only need Windows PowerShell/CMD (use a different MCP server)

Features

📊 Information Gathering (Read-Only)

• 🖥️ Get system information (OS, kernel, hostname)
• 📁 Browse directory contents
• 💾 Check disk usage
• ⚙️ List environment variables
• 🔄 Monitor running processes

🔧 Command Execution (With Safety)

• 🔒 Secure command execution in WSL environments
• ⚡ Built-in safety features:
  • Dangerous command detection
  • Command confirmation system
  • Path traversal prevention
  • Command sanitization
• 📁 Working directory support
• ⏱️ Command timeout functionality
• 🛡️ Protection against shell injection

Configuration

This server requires configuration through your MCP client. Here are

examples for different environments:

Cline Configuration

Add this to your Cline MCP settings:

{
	"mcpServers": {
		"mcp-wsl-exec": {
			"command": "npx",
			"args": ["-y", "mcp-wsl-exec"]
		}
	}
}

Claude Desktop Configuration

Add this to your Claude Desktop configuration:

{
	"mcpServers": {
		"mcp-wsl-exec": {
			"command": "npx",
			"args": ["-y", "mcp-wsl-exec"]
		}
	}
}

API

The server provides 7 MCP tools:

Information Gathering (Read-Only) 📊

These tools provide context about your WSL environment without making

changes:

get_system_info

Get system information (OS version, kernel, hostname).

Parameters: None

get_directory_info

Get directory contents and file information.

Parameters:

• `path` (string, optional): Directory path (defaults to current

directory)

• `details` (boolean, optional): Show detailed information

(permissions, sizes, etc.)

get_disk_usage

Get disk space information.

Parameters:

• `path` (string, optional): Specific path to check (defaults to all

filesystems)

get_environment

Get environment variables.

Parameters:

• `filter` (string, optional): Filter pattern to search for specific

variables

list_processes

List running processes.

Parameters:

• `filter` (string, optional): Filter by process name

Command Execution (Potentially Destructive) 🔧

Use these tools when you need to make changes or run custom commands:

execute_command

Execute a command in WSL with safety checks and validation.

Parameters:

• `command` (string, required): Command to execute
• `working_dir` (string, optional): Working directory for command

execution

• `timeout` (number, optional): Timeout in milliseconds

Note: Dangerous commands will require confirmation via

`confirm_command`.

confirm_command

Confirm execution of a dangerous command that was flagged by safety

checks.

Parameters:

• `confirmation_id` (string, required): Confirmation ID received from

execute_command

• `confirm` (boolean, required): Whether to proceed with the command

execution

Safety Features

Dangerous Command Detection

The server maintains a list of potentially dangerous commands that

require explicit confirmation before execution, including:

• File system operations (rm, rmdir, mv)
• System commands (shutdown, reboot)
• Package management (apt, yum, dnf)
• File redirections (>, >>)
• Permission changes (chmod, chown)
• And more...

Command Validation

Commands are executed through `bash -c`, so normal shell syntax such

as pipes, quotes, redirects, and command chaining is preserved. The

server validates empty/null-byte inputs, quotes arguments used by

built-in tools, and requires confirmation for potentially dangerous

commands.

Development

Setup

1. Clone the repository

2. Install dependencies:

pnpm install

3. Build the project:

pnpm build

4. Run in development mode:

pnpm dev

Publishing

The project uses changesets for version management. To publish:

1. Create a changeset:

pnpm changeset

2. Version the package:

pnpm changeset version

3. Publish to npm:

pnpm release

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see the LICENSE file for details.

Acknowledgments

• Built on the

Model Context Protocol

• Designed for secure WSL command execution