WSL Exec

Execute commands securely in Windows Subsystem for Linux (WSL).

GitHub
20

Documentation

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
  1. Build the project:
pnpm build
  1. Run in development mode:
pnpm dev

Publishing

The project uses changesets for version management. To publish:

  1. Create a changeset:
pnpm changeset
  1. Version the package:
pnpm changeset version
  1. 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