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

<a href="https://glama.ai/mcp/servers/wv6df94kb8">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/wv6df94kb8/badge" />
</a>

## ⚠️ 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:

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

### Claude Desktop Configuration

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:

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

```bash
pnpm install
```

3. Build the project:

```bash
pnpm build
```

4. Run in development mode:

```bash
pnpm dev
```

### Publishing

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](LICENSE) file for details.

## Acknowledgments

- Built on the
  [Model Context Protocol](https://github.com/modelcontextprotocol)
- Designed for secure WSL command execution