wsl-mcp-server

sirredbeard/wsl-mcp-server

3.2

If you are the rightful owner of wsl-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A powerful Model Context Protocol (MCP) server built with .NET 10 that enables AI-powered configuration and management of Windows Subsystem for Linux (WSL).

Tools
5
Resources
0
Prompts
0

WSL MCP Server - Intelligent WSL Management

A powerful Model Context Protocol (MCP) server built with .NET 10 that enables AI-powered configuration and management of Windows Subsystem for Linux (WSL). Features intelligent agents using Microsoft Semantic Kernel and machine learning capabilities for optimization and predictions.

🚀 Features

Core WSL Management

  • Distribution Management: List, install, start, stop, export, and import WSL distributions
  • Command Execution: Run commands in any WSL distribution
  • Configuration: Modify WSL settings (memory, CPU, swap, etc.) via .wslconfig
  • File Operations: Copy files between Windows and WSL filesystems
  • System Information: Get detailed WSL version and status information

🤖 AI-Powered Intelligence

  • Semantic Kernel Agents: Complex task planning and execution with natural language understanding
  • Performance Analysis: ML-powered insights into WSL resource usage and bottlenecks
  • Smart Recommendations: AI-generated optimization suggestions based on system metrics
  • Resource Prediction: Predict resource requirements for different workload types
  • Automated Task Planning: Break down complex operations into manageable steps

🎯 Windows 11 ML Integration

  • Performance trend analysis
  • Bottleneck detection
  • Workload-specific resource recommendations
  • Health scoring and diagnostics

📋 Prerequisites

  • Windows 11 (22H2 or later recommended)
  • WSL 2 installed and configured
  • .NET 10 SDK
  • (Optional) OpenAI API key for advanced agent features

🛠️ Installation

1. Clone or Download

cd d:\wsl-mcp-agent

2. Restore Dependencies

dotnet restore

3. Build the Project

dotnet build

4. (Optional) Configure AI Features

For Semantic Kernel agent features, set environment variables:

$env:OPENAI_API_KEY = "your-api-key-here"

Or use Azure OpenAI:

$env:AZURE_OPENAI_ENDPOINT = "your-endpoint"
$env:AZURE_OPENAI_KEY = "your-key"

5. Run the Server

dotnet run

📖 MCP Tools Reference

Basic WSL Operations

wsl_list_distros

List all installed WSL distributions with status information.

Arguments: None

Example Response:

[
  {
    "name": "Ubuntu",
    "isDefault": true,
    "state": "Running",
    "version": "2"
  }
]
wsl_get_info

Get WSL version and system information.

Arguments: None

wsl_install_distro

Install a new WSL distribution.

Arguments:

  • distro (string): Distribution name (e.g., "Ubuntu", "Debian", "Kali-Linux")
wsl_start_distro

Start or wake up a WSL distribution.

Arguments:

  • distro (string): Distribution name to start
wsl_stop_distro

Stop/terminate a running WSL distribution.

Arguments:

  • distro (string): Distribution name to stop
wsl_execute_command

Execute a command in a WSL distribution.

Arguments:

  • distro (string): Distribution name
  • command (string): Command to execute

Example:

{
  "distro": "Ubuntu",
  "command": "uname -a"
}

Configuration & Management

wsl_configure

Configure WSL settings (memory, processors, swap, etc.).

Arguments:

  • settings (object): Configuration object

Example:

{
  "settings": {
    "memory": "8GB",
    "processors": "4",
    "swap": "4GB",
    "localhostForwarding": "true"
  }
}
wsl_export_distro

Export a WSL distribution to a tar file.

Arguments:

  • distro (string): Distribution name
  • output_path (string): Path for tar file (e.g., "C:\backups\ubuntu.tar")
wsl_import_distro

Import a WSL distribution from a tar file.

Arguments:

  • distro (string): New distribution name
  • tar_path (string): Path to tar file
  • install_path (string): Installation location

File Operations

wsl_copy_from_wsl

Copy files from WSL to Windows.

Arguments:

  • distro (string): Distribution name
  • wsl_path (string): Source path in WSL (e.g., "/home/user/file.txt")
  • windows_path (string): Destination in Windows (e.g., "C:\temp\file.txt")
wsl_copy_to_wsl

Copy files from Windows to WSL.

Arguments:

  • distro (string): Distribution name
  • windows_path (string): Source path in Windows
  • wsl_path (string): Destination in WSL

🤖 AI Agent Features

wsl_agent_task

Use AI agent to perform complex WSL tasks with planning and reasoning.

Arguments:

  • task (string): Natural language task description
  • context (string, optional): Additional context or constraints

Example:

{
  "task": "Set up a new Ubuntu distribution optimized for Docker development",
  "context": "I need at least 16GB memory and want to enable systemd"
}
wsl_get_recommendations

Get AI-powered recommendations for WSL optimization.

Arguments:

  • distro (string, optional): Specific distribution name

Example Response:

{
  "score": 75,
  "items": [
    {
      "category": "Memory",
      "priority": "High",
      "title": "High Memory Usage Detected",
      "description": "Current memory usage is 85%",
      "action": "Add 'memory=8GB' to .wslconfig",
      "expectedImpact": "Improved performance and reduced swapping"
    }
  ]
}
wsl_analyze_performance

Analyze WSL performance and resource usage with ML insights.

Arguments:

  • distro (string, optional): Specific distribution name
wsl_predict_resources

Predict future resource requirements using ML.

Arguments:

  • distro (string): Distribution name
  • workload (string): Workload description (e.g., "Docker containers", "ML training", "web development")

Example:

{
  "distro": "Ubuntu",
  "workload": "Running multiple Docker containers for microservices development"
}

Example Response:

{
  "recommendedMemoryGb": 16,
  "recommendedCpuCores": 6,
  "recommendedDiskGb": 100,
  "confidence": 0.90,
  "reasoning": "Container workloads require substantial resources"
}

🎮 Usage Examples

Example 1: Basic WSL Management

// List all distributions
{"tool": "wsl_list_distros"}

// Start Ubuntu
{"tool": "wsl_start_distro", "arguments": {"distro": "Ubuntu"}}

// Execute command
{"tool": "wsl_execute_command", "arguments": {
  "distro": "Ubuntu",
  "command": "df -h"
}}

Example 2: Configuration

// Configure WSL for high-performance workloads
{"tool": "wsl_configure", "arguments": {
  "settings": {
    "memory": "16GB",
    "processors": "8",
    "swap": "8GB",
    "nestedVirtualization": "true",
    "vmIdleTimeout": "60000"
  }
}}

Example 3: AI-Powered Task Execution

// Let the agent handle complex setup
{"tool": "wsl_agent_task", "arguments": {
  "task": "Install and configure a new Debian distribution for Python data science work",
  "context": "Need Jupyter, pandas, numpy, and scikit-learn"
}}

// Get performance recommendations
{"tool": "wsl_get_recommendations", "arguments": {
  "distro": "Ubuntu"
}}

// Predict resources for workload
{"tool": "wsl_predict_resources", "arguments": {
  "distro": "Ubuntu",
  "workload": "Training machine learning models with TensorFlow"
}}

Example 4: Backup and Migration

// Export current distribution
{"tool": "wsl_export_distro", "arguments": {
  "distro": "Ubuntu",
  "output_path": "C:\\Backups\\ubuntu-backup.tar"
}}

// Import to new location
{"tool": "wsl_import_distro", "arguments": {
  "distro": "Ubuntu-Dev",
  "tar_path": "C:\\Backups\\ubuntu-backup.tar",
  "install_path": "C:\\WSL\\Ubuntu-Dev"
}}

🏗️ Architecture

Technology Stack

  • .NET 10: Latest .NET features including Native AOT support
  • Model Context Protocol: MCP SDK for tool registration and communication
  • Microsoft Semantic Kernel: AI agent orchestration and planning
  • Microsoft.ML: Machine learning for predictions and recommendations
  • Windows SDK: Native Windows integration

Project Structure

WslMcpServer/
├── Program.cs                    # MCP server initialization and tool registration
├── Services/
│   └── WslService.cs            # Core WSL operations via wsl.exe
├── Agents/
│   ├── WslAgentService.cs       # Semantic Kernel agent integration
│   └── WslIntelligenceService.cs # ML-powered analytics and predictions
└── WslMcpServer.csproj          # Project configuration

⚙️ Configuration

WSL Configuration (.wslconfig)

The server can modify %USERPROFILE%\.wslconfig:

[wsl2]
memory=8GB              # Memory allocation
processors=4            # CPU cores
swap=4GB               # Swap space
localhostForwarding=true
nestedVirtualization=true
vmIdleTimeout=60000
dnsTunneling=true      # Improved network performance

Environment Variables

  • OPENAI_API_KEY: OpenAI API key for agent features
  • AZURE_OPENAI_ENDPOINT: Azure OpenAI endpoint
  • AZURE_OPENAI_KEY: Azure OpenAI key

🔍 Troubleshooting

WSL Not Found

Ensure WSL is installed:

wsl --install

Permission Issues

Run as Administrator if needed:

Start-Process powershell -Verb RunAs

Agent Features Not Working

  1. Verify AI credentials are set
  2. Check network connectivity
  3. Review logs for detailed errors

🚧 Development

Build for Production

dotnet publish -c Release -r win-x64 --self-contained

Run Tests

dotnet test

Enable Debug Logging

Modify appsettings.json or set:

$env:DOTNET_ENVIRONMENT = "Development"

📝 License

See LICENSE file for details.

🤝 Contributing

Contributions welcome! This project showcases:

  • Latest .NET 10 features
  • MCP server implementation
  • AI agent integration with Semantic Kernel
  • Windows ML capabilities
  • WSL automation

🔗 Related Resources

💡 Advanced Use Cases

  1. Automated Development Environments: Create consistent dev environments across teams
  2. CI/CD Integration: Manage WSL environments for build pipelines
  3. Multi-Distribution Testing: Test across different Linux distributions
  4. Resource Optimization: AI-powered resource allocation based on workload
  5. Disaster Recovery: Automated backup and restore procedures
  6. Performance Monitoring: Continuous analysis and optimization recommendations

Built with .NET 10 🚀 | Powered by AI 🤖 | For Windows 11 💻