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

$3

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

$3

- 🔒 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:

$3

Add this to your Cline MCP settings:

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

$3

Add this to your Claude Desktop configuration:

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

API

The server provides 7 MCP tools:

$3

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

$3

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

$3

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...

$3

All commands are sanitized to prevent:

- Shell metacharacter injection
- Path traversal attempts
- Home directory references
- Dangerous command chaining

Development

$3

1. Clone the repository
2. Install dependencies:

`bash
pnpm install
`

3. Build the project:

`bash
pnpm build
`

4. Run in development mode:

`bash
pnpm dev
`

$3

The project uses changesets for version management. To publish:

1. Create a changeset:

`bash
pnpm changeset
`

2. Version the package:

`bash
pnpm changeset version
`

3. Publish to npm:

`bash
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