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 executeworking_dir(string, optional): Working directory for command executiontimeout(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_commandconfirm(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 Sanitization
All commands are sanitized to prevent:
- Shell metacharacter injection
- Path traversal attempts
- Home directory references
- Dangerous command chaining
Development
Setup
- Clone the repository
- Install dependencies:
pnpm install
- Build the project:
pnpm build
- Run in development mode:
pnpm dev
Publishing
The project uses changesets for version management. To publish:
- Create a changeset:
pnpm changeset
- Version the package:
pnpm changeset version
- 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