Windows CLI MCP Server (Enhanced)

MCP server for secure command-line interactions on Windows systems, enabling controlled access to PowerShell, CMD, Git Bash, and Bash shells. It allows MCP clients (like Claude Desktop) to perform operations on your system, similar to Open Interpreter.

This enhanced version includes advanced configuration management, improved security features, and comprehensive testing capabilities.

[!IMPORTANT] This MCP server provides direct access to your system's command line interface. When enabled, it grants access to your files, environment variables, and command execution capabilities.

Review and restrict allowed paths

Enable directory restrictions

Configure command blocks

Consider security implications

See Configuration for more details.

Windows CLI MCP Server (Enhanced)

Features

Multi-Shell Support: Execute commands in PowerShell, Command Prompt (CMD), Git Bash, Bash, and WSL
Inheritance-Based Configuration: Global defaults with shell-specific overrides
Shell-Specific Validation: Each shell can have its own security settings and path formats
Flexible Path Management: Different shells support different path formats (Windows/Unix/Mixed)
Resource Exposure: View configuration and security settings as MCP resources
Explicit Working Directory State: The server maintains an active working directory used when execute_command omits workingDir. If the launch directory isn't allowed, this state starts unset and must be set via set_current_directory.
Optional Initial Directory: Configure initialDir to start the server in a specific directory.
Security Controls:
- Command blocking (full paths, case variations)
- Working directory validation
- Maximum command length limits
- Smart argument validation
- Shell-specific timeout settings
Configurable:
- Inheritance-based configuration system
- Shell-specific security overrides
- Dynamic tool descriptions based on enabled shells

See the API section for more details on the tools and resources the server provides to MCP clients.

Note: The server will only allow operations within configured directories, with allowed commands.

Log Management

wcli0 automatically stores command execution logs and provides MCP resources for querying historical output with advanced filtering capabilities.

Output Truncation

By default, command responses show only the last 20 lines to prevent overwhelming long outputs. Full output is always stored and accessible via log resources. Configure truncation settings:

{
  "global": {
    "logging": {
      "maxOutputLines": 20,
      "enableTruncation": true
    }
  }
}

Log Resources

Access stored command output via MCP resources:

cli://logs/list - List all stored command execution logs
cli://logs/recent?n=10 - Get the N most recent logs
cli://logs/commands/{id} - Access full output from a specific command
cli://logs/commands/{id}/range?start=1&end=100 - Query specific line ranges
cli://logs/commands/{id}/search?q=error&context=3 - Search logs with context

See API Documentation for detailed resource specifications and query parameters.

Configuration

{
  "global": {
    "logging": {
      "maxOutputLines": 20,
      "enableTruncation": true,
      "maxStoredLogs": 50,
      "maxLogSize": 1048576,
      "enableLogResources": true,
      "logRetentionMinutes": 60
    }
  }
}

Usage with Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "windows-cli": {
      "command": "npx",
      "args": ["-y", "wcli0"]
    }
  }
}

For use with a specific config file, add the --config flag:

{
  "mcpServers": {
    "windows-cli": {
      "command": "npx",
      "args": [
        "-y",
        "wcli0",
        "--config",
        "path/to/your/config.json"
      ]
    }
  }
}

Configuration Setup

To get started with configuration:

Use a sample configuration:
- Copy config.examples/config.sample.json for basic setup
- Copy config.examples/config.development.json for development environments
- Copy config.examples/config.secure.json for high-security environments
- Copy config.examples/emptyRestrictions.json to remove all default restrictions
Create your own configuration:
```
# Copy and customize a sample
cp config.examples/config.sample.json my-config.json

# Or generate a default config
npx wcli0 --init-config ./my-config.json
```
The server also accepts an --initialDir flag to override the initial working directory defined in your configuration file:
```
npx wcli0 --config ./my-config.json --initialDir /path/to/start
```
You can override global command limits directly from the CLI:
```
npx wcli0 --config ./my-config.json \
  --maxCommandLength 5000 --commandTimeout 60
```
You can override blocked restrictions directly from the CLI. Pass the option with an empty string to clear defaults:
```
npx wcli0 --blockedCommand "" --blockedArgument "" --blockedOperator ""
```
Provide the flag multiple times to specify values:
```
npx wcli0 --blockedCommand rm --blockedCommand del
```
You can also start the server with a specific shell and allowed directories without a configuration file:
```
npx wcli0 --shell powershell \
  --allowedDir C:\safe --allowedDir D:\projects
```
For WSL shells, you can specify a custom mount location:

npx wcli0 --shell wsl \
  --wslMountPoint /windows/

To disable directory restrictions entirely when no allowed paths are configured, start the server with:

npx wcli0 --allowAllDirs

When started this way, restrictWorkingDirectory is forced on and enableInjectionProtection is disabled to ensure the allowed paths apply without shell injection checks.

Update your Claude Desktop configuration to use your config file:

{
  "mcpServers": {
    "windows-cli": {
      "command": "npx",
      "args": [
        "-y",
        "wcli0",
        "--config",
        "./my-config.json"
      ]
    }
  }
}

After configuring, you can:

Execute commands directly using the available tools
View server configuration and security settings in the Resources section
Access shell-specific configurations and capabilities

Configuration

The server uses an inheritance-based configuration system where global defaults can be overridden by shell-specific settings.

Configuration Structure

{
  "global": {
    "security": {
      "maxCommandLength": 2000,
      "commandTimeout": 30,
      "enableInjectionProtection": true,
      "restrictWorkingDirectory": true
    },
    "restrictions": {
      "blockedCommands": ["format", "shutdown"],
      "blockedArguments": ["--exec", "-e"],
      "blockedOperators": ["&", "|", ";", "`"]
    },
    "paths": {
      "allowedPaths": ["/home/user", "/tmp"],
      "initialDir": "/home/user"
    }
  },
  "shells": {
    "powershell": {
      "type": "powershell",
      "enabled": true,
      "executable": {
        "command": "powershell.exe",
        "args": ["-NoProfile", "-NonInteractive", "-Command"]
      },
      "overrides": {
        "security": {
          "commandTimeout": 45
        },
        "restrictions": {
          "blockedCommands": ["Remove-Item", "Format-Volume"]
        }
      }
    },
    "wsl": {
      "type": "wsl",
      "enabled": true,
      "executable": {
        "command": "wsl.exe",
        "args": ["-e"]
      },
      "wslConfig": {
        "mountPoint": "/mnt/",
        "inheritGlobalPaths": true
      }
    }
  }
}

Configuration Locations

The server looks for configuration files in the following order:

Path specified via --config command line argument
win-cli-mcp.config.json in the current working directory
~/.win-cli-mcp/config.json in user's home directory

If no configuration file is found, the server will use a default (restricted) configuration.

Default Configuration

Note: The default configuration is designed to be restrictive and secure. Find more details on each setting in the Configuration Settings section.

{
  "global": {
    "security": {
      "maxCommandLength": 2000,
      "commandTimeout": 30,
      "enableInjectionProtection": true,
      "restrictWorkingDirectory": true
    },
    "restrictions": {
      "blockedCommands": [
        "rm", "del", "rmdir", "format", "shutdown", "restart",
        "reg", "regedit", "net", "netsh", "takeown", "icacls"
      ],
      "blockedArguments": [
        "--exec", "-e", "/c", "-enc", "-encodedcommand",
        "-command", "--interactive", "-i", "--login", "--system"
      ],
      "blockedOperators": ["&", "|", ";", "`"]
    },
    "paths": {
      "initialDir": null
    }
  },
  "shells": {
    "powershell": {
      "type": "powershell",
      "enabled": true,
      "executable": {
        "command": "powershell.exe",
        "args": ["-NoProfile", "-NonInteractive", "-Command"]
      }
    },
    "cmd": {
      "type": "cmd",
      "enabled": true,
      "executable": {
        "command": "cmd.exe",
        "args": ["/c"]
      }
    },
    "gitbash": {
      "type": "gitbash",
      "enabled": true,
      "executable": {
        "command": "C:\\Program Files\\Git\\bin\\bash.exe",
        "args": ["-c"]
      }
    }
  }
}

Configuration Settings

The configuration file uses an inheritance system with two main sections: global and shells.

Global Settings

Global settings provide defaults that apply to all shells unless overridden.

Security Settings

{
  "global": {
    "security": {
      // Maximum allowed length for any command
      "maxCommandLength": 2000,
      
      // Command execution timeout in seconds
      "commandTimeout": 30,
      
      // Enable protection against command injection
      "enableInjectionProtection": true,
      
      // Restrict commands to allowed working directories
      "restrictWorkingDirectory": true
    }
  }
}

Restriction Settings

{
  "global": {
    "restrictions": {
      // Commands to block - blocks both direct use and full paths
      "blockedCommands": ["rm", "format", "shutdown"],
      
      // Arguments to block across all commands
      "blockedArguments": ["--exec", "-e", "/c"],
      
      // Operators to block in commands
      "blockedOperators": ["&", "|", ";", "`"]
    }
  }
}

Path Settings

{
  "global": {
    "paths": {
      // Directories where commands can be executed
      "allowedPaths": ["/home/user", "/tmp", "C:\\Users\\username"],
      
      // Initial working directory (null = use launch directory)
      "initialDir": "/home/user",
      
      // Whether to restrict working directories
      "restrictWorkingDirectory": true
    }
  }
}

If the allowedPaths array is omitted from your configuration file, no default directories are automatically allowed. When restrictWorkingDirectory is enabled, only the initialDir (if specified) will be added to the allowed paths list. Use the --allowAllDirs flag when launching the server to automatically disable restrictWorkingDirectory if no allowed paths or initialDir are set.

Shell Configuration

Each shell can be individually configured and can override global settings. Each shell entry must include a type field indicating the shell. Valid values are powershell, cmd, gitbash, bash, and wsl.

Basic Shell Configuration

{
  "shells": {
    "powershell": {
      "type": "powershell",
      "enabled": true,
      "executable": {
        "command": "powershell.exe",
        "args": ["-NoProfile", "-NonInteractive", "-Command"]
      }
    }
  }
}

Shell-Specific Overrides

{
  "shells": {
    "powershell": {
      "type": "powershell",
      "enabled": true,
      "executable": {
        "command": "powershell.exe",
        "args": ["-NoProfile", "-NonInteractive", "-Command"]
      },
      "overrides": {
        "security": {
          "commandTimeout": 45,
          "maxCommandLength": 3000
        },
        "restrictions": {
          "blockedCommands": ["Remove-Item", "Format-Volume"],
          "blockedOperators": ["|", "&"]
        }
      }
    }
  }
}

WSL Configuration

WSL shells have additional configuration options for path mapping:

{
  "shells": {
    "wsl": {
      "type": "wsl",
      "enabled": true,
      "executable": {
        "command": "wsl.exe",
        "args": ["-e"]
      },
      "wslConfig": {
        "mountPoint": "/mnt/",
        "inheritGlobalPaths": true
      }
    }
  }
}

You can override the mount point at startup using the --wslMountPoint CLI flag.

Configuration Inheritance

The inheritance system works as follows:

Global defaults are applied to all shells
Shell-specific overrides replace or extend global settings
Array settings (like blockedCommands) override defaults when provided. Specifying an empty array removes all default entries for that setting.
Object settings are deep-merged
Primitive settings are replaced

Example of inheritance in action:

{
  "global": {
    "security": { "commandTimeout": 30 },
    "restrictions": { "blockedCommands": ["rm", "format"] }
  },
  "shells": {
    "powershell": {
      "type": "powershell",
      "overrides": {
        "security": { "commandTimeout": 45 },
        "restrictions": { "blockedCommands": ["Remove-Item"] }
      }
    }
  }
}

Results in PowerShell having:

commandTimeout: 45 (overridden)
blockedCommands: ["Remove-Item"] (overrides defaults)

To completely remove defaults for a given restriction, provide an empty array:

{
  "global": {
    "restrictions": {
      "blockedCommands": [],
      "blockedArguments": [],
      "blockedOperators": []
    }
  },
  "shells": {
    "powershell": {
      "type": "powershell",
      "overrides": {
        "restrictions": { "blockedCommands": [] }
      }
    }
  }
}

API

Tools

execute_command
- Execute a command in the specified shell
- Inputs:
  - shell (string): Shell to use ("powershell", "cmd", "gitbash", "bash", or "wsl")
  - command (string): Command to execute
  - workingDir (optional string): Working directory
- Returns command output as text, or error message if execution fails
- If workingDir is omitted, the command runs in the server's active working directory. If this has not been set, the tool returns an error.
get_current_directory
- Get the server's active working directory
- If the directory is not set, returns a message explaining how to set it
set_current_directory
- Set the server's active working directory
- Inputs:
  - path (string): Path to set as current working directory
- Returns confirmation message with the new directory path, or error message if the change fails
get_config
- Get the windows CLI server configuration
- Returns the server configuration as a JSON string (excluding sensitive data)
validate_directories
- Check if specified directories are within allowed paths
- Only available when restrictWorkingDirectory is enabled in configuration
- Inputs:
  - directories (array of strings): List of directory paths to validate
- Returns success message if all directories are valid, or error message detailing which directories are outside allowed paths

Resources

cli://config
- Returns the main CLI server configuration (excluding sensitive data like blocked command details if security requires it).
cli://logs/list
- List all stored command execution logs with metadata
cli://logs/recent?n={count}
- Get the N most recent command logs (default: 5)
cli://logs/commands/{id}
- Access full output from a specific command execution
cli://logs/commands/{id}/range?start={n}&end={m}
- Query specific line ranges from a log (supports negative indices)
cli://logs/commands/{id}/search?q={pattern}&context={n}&occurrence={n}
- Search logs with regex patterns and context lines

Security Considerations

This server allows external tools to execute commands on your system. Exercise extreme caution when configuring and using it.

Built-in Security Features

Path Restrictions: Commands can only be executed in specified directories (allowedPaths) if restrictWorkingDirectory is true.
Command Blocking: Defined commands and arguments are blocked to prevent potentially dangerous operations (blockedCommands, blockedArguments).
Injection Protection: Common shell injection characters (;, &, |, `) are blocked in command strings if enableInjectionProtection is true.
Timeout: Commands are terminated if they exceed the configured timeout (commandTimeout).
Input validation: All user inputs are validated before execution
Shell process management: Processes are properly terminated after execution or timeout

Configurable Security Features (Active by Default)

Working Directory Restriction (restrictWorkingDirectory): HIGHLY RECOMMENDED. Limits command execution to safe directories.
Injection Protection (enableInjectionProtection): Recommended to prevent bypassing security rules.

Best Practices

Minimal Allowed Paths: Only allow execution in necessary directories.
Restrictive Blocklists: Block any potentially harmful commands or arguments.
Regularly Review Logs: Check the command history for suspicious activity.
Keep Software Updated: Ensure Node.js, npm, and the server itself are up-to-date.

Using the MCP Inspector for Testing

Use the Inspector to interactively test this server with a custom config file. Pass any server flags after --:

# Inspect with built server and test config
npx @modelcontextprotocol/inspector -- node dist/index.js --config tests/config.json

# Or test the published package
npx @modelcontextprotocol/inspector wcli0 -- --config tests/config.json

Development and Testing

This project requires Node.js 18 or later.

Running Tests

# Install dependencies
npm install

# Run all tests
npm test

# Run specific test suites
npm run test:validation    # Path validation tests
npm run test:wsl          # WSL emulation tests
npm run test:integration  # Integration tests
npm run test:async        # Async operation tests

# Run tests with coverage
npm run test:coverage

# Debug open handles
npm run test:debug

Cross-Platform Testing

The project uses a Node.js-based WSL emulator (scripts/wsl-emulator.js) to enable testing of WSL functionality on all platforms. This allows the test suite to run successfully on both Windows and Linux environments.

Acknowledgments

This project is based on the excellent work by SimonB97 in the win-cli-mcp-server repository. Due to significant configuration differences and architectural changes that made merging back to the source repository challenging, this has been maintained as a separate fork with enhanced features and extensive modifications.

Key enhancements in this version:

Enhanced inheritance-based configuration system
Improved WSL support with cross-platform testing
Advanced security features and path validation
Comprehensive test coverage with Node.js-based WSL emulation
Extended documentation and configuration examples

We gratefully acknowledge SimonB97's foundational work that made this project possible.

Development Environment using Dev Containers

This project includes a Dev Container configuration, which allows you to use a Docker container as a fully-featured development environment. This ensures consistency and makes it easy to get started with development and testing.

Prerequisites

Docker Desktop installed and running.
Visual Studio Code installed.
The Dev Containers extension installed in VS Code.

Getting Started

Clone this repository to your local machine.
Open the repository in Visual Studio Code.
When prompted "Reopen in Container", click the button. (If you don't see a prompt, you can open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P) and select "Dev Containers: Reopen in Container".)
VS Code will build the dev container image (as defined in .devcontainer/devcontainer.json and Dockerfile) and start the container. This might take a few minutes the first time.
Once the container is built and started, your VS Code will be connected to this environment. The postCreateCommand (npm install) will ensure all dependencies are installed.

Running Tests in the Dev Container

After opening the project in the dev container:

Open a new terminal in VS Code (it will be a terminal inside the container).
Run the tests using the command:
```
npm test
```

This setup mirrors the environment used in GitHub Actions for tests, ensuring consistency between local development and CI.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Windows CLI

Windows CLI MCP Server (Enhanced)

Features

Log Management

Output Truncation

Log Resources

Configuration

Usage with Claude Desktop

Configuration Setup

Configuration

Configuration Structure

Configuration Locations

Default Configuration

Configuration Settings

Global Settings

Security Settings

Restriction Settings

Path Settings

Shell Configuration

Basic Shell Configuration

Shell-Specific Overrides

WSL Configuration

Configuration Inheritance

API

Tools

Resources

Security Considerations

Built-in Security Features

Configurable Security Features (Active by Default)

Best Practices

Using the MCP Inspector for Testing

Development and Testing

Running Tests

Cross-Platform Testing

Acknowledgments

Development Environment using Dev Containers

Prerequisites

Getting Started

Running Tests in the Dev Container

License

Related Servers

Scanpy-MCP

Remote MCP Server (Authless)

Authless Remote MCP Server

Advanced Unity MCP Integration

SwarmTask

Nexus MCP Bridge for VSCode

Nextflow Developer Tools

Angular MCP Server

idb-mcp

MCP Feedback Enhanced