Windows Command-Line Management & Proxy (MCP) Host

[!CAUTION] PROJECT STATUS: RETIRED - Maintenance ceased. Users should migrate to the successor project: https://github.com/wonderwhy-er/DesktopCommanderMCP for continued functionality.

This MCP compliant backend service establishes a secure channel for artificial intelligence agents (such as Claude Desktop, via MCP clients) to interact with the underlying Windows operating system. It strictly mediates access to native command interpreters (PowerShell, Command Prompt, Git Bash) and facilitates remote shell operations over SSH. This tool functions similarly to Open Interpreter but is tailored for the MCP framework.

[!IMPORTANT] SECURITY WARNING: Activating this service grants external entities potential access to execute arbitrary commands, read/write files, and manage network resources (via SSH) on the host machine. Strict configuration is mandatory.

Key security measures: - Rigorous path sandboxing - Pre-execution command/argument filtering - Explicit allowance lists for SSH endpoints

Refer to the Configuration Section for hardening instructions.

Core Capabilities
Integration Guide (Claude Desktop)
Configuration Schema
Location Resolution
Default Secure Settings
Fine-Tuning Parameters
Interface Definition (API)
Exposed Tools
System Resources
Security Posture
Licensing

Core Capabilities

Interpreter Versatility: Command dispatch capability across PowerShell, native CMD, and Git Bash environments.
Remote Execution: Secure command routing to defined remote hosts via the Secure Shell protocol.
System Introspection: Exposes connectivity states, current execution directory, and configuration details as queryable MCP resources.
Granular Access Control:
Whitelisting/Blacklisting of specific executables and associated parameters.
Working directory enforcement checks.
Command execution time limits.
Comprehensive execution logging and historical tracking.
Advanced argument sanitation.
High Customizability:
Definition of unique security policy sets.
Per-shell operational parameters.
Persistent profiles for SSH endpoints.
Boundary definitions for filesystem access.
Blocked command signatures.

Consult the API Reference for a full enumeration of callable instruments available to MCP consumers.

Operational Constraint: The service strictly confines all operations to directories explicitly defined in the configuration and restricts execution to authorized command sets and established SSH targets.

Integration Guide (Claude Desktop)

To link this host service with your Claude Desktop instance, modify your configuration file (claude_desktop_config.json) as follows:

{
  "mcpServers": {
    "windows-cli": {
      "command": "npx",
      "args": ["-y", "@simonb97/server-win-cli"]
    }
  }
}

To employ a custom configuration file instead of defaults, incorporate the --config switch:

{
  "mcpServers": {
    "windows-cli": {
      "command": "npx",
      "args": [
        "-y",
        "@simonb97/server-win-cli",
        "--config",
        "/path/to/your/custom_settings.json"
      ]
    }
  }
}

Once configured, interaction possibilities include: - Direct command execution using the exposed instrument suite. - Querying server state and SSH profiles via the Resources panel. - Management of SSH sessions through specialized API tools.

Configuration

The operational behavior is governed by a central JSON definition file, allowing for granular tuning of security posture, shell invocation settings, and SSH profiles.

Initialization of a configuration file can be achieved by:

a) Duplicating the provided config.json.example to config.json, or

b) Executing the setup utility:

npx @simonb97/server-win-cli --init-config ./config.json

Subsequently, point the integration to this file using the --config directive, as demonstrated in the Integration Guide.

Configuration Locations

The system searches for the configuration file in this prioritized sequence:

Location specified via the --config command-line argument.
config.json within the execution directory.
~/.win-cli-mcp/config.json within the invoking user's home directory.

If no file is detected, the server defaults to a highly restricted, baseline configuration set.

Default Secure Settings

Note: The embedded default configuration prioritizes system safety. Detailed documentation for every setting resides in the Configuration Settings subsection.

{
  "security": {
    "maxCommandLength": 2000,
    "blockedCommands": [
      "rm", "del", "rmdir", "format", "shutdown", "restart", 
      "reg", "regedit", "net", "netsh", "takeown", "icacls"
    ],
    "blockedArguments": [
      "--exec", "-e", "/c", "-enc", "-encodedcommand", "-command", 
      "--interactive", "-i", "--login", "--system"
    ],
    "allowedPaths": ["User's home directory", "Current working directory"],
    "restrictWorkingDirectory": true,
    "logCommands": true,
    "maxHistorySize": 1000,
    "commandTimeout": 30,
    "enableInjectionProtection": true
  },
  "shells": {
    "powershell": {
      "enabled": true,
      "command": "powershell.exe",
      "args": ["-NoProfile", "-NonInteractive", "-Command"],
      "blockedOperators": ["&", "|", ";", "`"]
    },
    "cmd": {
      "enabled": true,
      "command": "cmd.exe",
      "args": ["/c"],
      "blockedOperators": ["&", "|", ";", "`"]
    },
    "gitbash": {
      "enabled": true,
      "command": "C:\\Program Files\\Git\\bin\\bash.exe",
      "args": ["-c"],
      "blockedOperators": ["&", "|", ";", "`"]
    }
  },
  "ssh": {
    "enabled": false,
    "defaultTimeout": 30,
    "maxConcurrentSessions": 5,
    "keepaliveInterval": 10000,
    "keepaliveCountMax": 3,
    "readyTimeout": 20000,
    "connections": {}
  }
}

Configuration Settings

The primary configuration structure consists of three distinct modules: security, shells, and ssh.

Safeguards & Auditing

{
  "security": {
    // Max allowable length for any submitted instruction string
    "maxCommandLength": 1000,

    // Signatures of executables forbidden for invocation. Blocks executables regardless of path specificity.
    // Example: Specifying "rm" prevents execution of "C:\System32\rm.exe". Case-insensitive matching is active.
    "blockedCommands": [
      "rm", // File obliteration
      "del", // File deletion
      "rmdir", // Directory removal
      "format", // Disk partitioning utility
      "shutdown", // System halt procedures
      "restart", // System reboot procedures
      "reg", // Registry modification utility
      "regedit", // Registry Editor invocation
      "net", // Networking configuration tools
      "netsh", // Advanced networking configuration
      "takeown", // File ownership reassignment
      "icacls" // Access Control List manipulation
    ],

    // Arguments that trigger a block when detected in any command invocation.
    // Validation occurs per argument, preventing false positives from blocked command names within arguments.
    "blockedArguments": [
      "--exec", // Direct execution flags
      "-e", // Abbreviated execution flags
      "/c", // Common command invocation wrapper in CMD/PowerShell
      "-enc", // PowerShell encoded command markers
      "-encodedcommand", // PowerShell encoded command markers
      "-command", // Direct instruction parameter for PowerShell
      "--interactive", // Flags suggesting interactive session takeover
      "-i", // Short interactive flag
      "--login", // Flags suggesting elevated login context
      "--system" // System-level operation flags
    ],

    // A whitelist dictating permissible execution directories.
    "allowedPaths": ["C:\Users\YourUsername", "C:\Projects"],

    // When true, execution is strictly confined to directories listed in allowedPaths.
    "restrictWorkingDirectory": true,

    // Persistence of command history is enabled.
    "logCommands": true,

    // Upper boundary on the number of historical entries retained.
    "maxHistorySize": 1000,

    // Timeout (seconds) imposed on all running processes.
    "commandTimeout": 30,

    // Protection mechanism against shell operator injection (e.g., chaining commands).
    "enableInjectionProtection": true
  }
}

Shell Environment Setup

{
  "shells": {
    "powershell": {
      // Activation status for PowerShell
      "enabled": true,
      // Path to the executable
      "command": "powershell.exe",
      // Standard initialization arguments
      "args": ["-NoProfile", "-NonInteractive", "-Command"],
      // Reserved symbols that denote command separation or piping; these are filtered.
      "blockedOperators": ["&", "|", ";", "`"]  
    },
    "cmd": {
      "enabled": true,
      "command": "cmd.exe",
      "args": ["/c"],
      "blockedOperators": ["&", "|", ";", "`"]
    },
    "gitbash": {
      "enabled": true,
      "command": "C:\\Program Files\\Git\\bin\\bash.exe",
      "args": ["-c"],
      "blockedOperators": ["&", "|", ";", "`"]
    }
  }
}

Remote Shell (SSH) Definitions

{
  "ssh": {
    // SSH module activation status
    "enabled": false,

    // Default inactivity timeout for remote commands (seconds)
    "defaultTimeout": 30,

    // Limit on simultaneous active remote connections
    "maxConcurrentSessions": 5,

    // Interval for sending 'keepalive' packets (ms) to maintain connection liveness
    "keepaliveInterval": 10000,

    // Max count of failed keepalive checks before session termination
    "keepaliveCountMax": 3,

    // Connection establishment timeout threshold (ms)
    "readyTimeout": 20000,

    // Predefined connection profiles for remote hosts
    "connections": {
      // Template Example: Local LAN Device
      "raspberry-pi": {
        "host": "raspberrypi.local", 
        "port": 22, 
        "username": "pi", 
        "password": "raspberry", 
        "keepaliveInterval": 10000, 
        "keepaliveCountMax": 3, 
        "readyTimeout": 20000 
      },
      // Template Example: Secured External Host using Key Auth
      "dev-server": {
        "host": "dev.example.com",
        "port": 22,
        "username": "admin",
        "privateKeyPath": "C:\\Users\YourUsername\.ssh\id_rsa", 
        "keepaliveInterval": 10000,
        "keepaliveCountMax": 3,
        "readyTimeout": 20000
      }
    }
  }
}

API

Exposed Tools

execute_command
Purpose: Invokes a command within the selected local operating environment.
Parameters:
- shell (string): Target environment identifier ("powershell", "cmd", or "gitbash").
- command (string): The instruction payload to be processed.
- workingDir (optional string): Directory context for execution.
Output: Standard output text or an error diagnostic string.
get_command_history
Purpose: Retrieves chronological records of past command executions.
Parameter:
- limit (optional number): Cap on the number of history entries returned.
Output: A list of timestamped command executions and their results.
ssh_execute
Purpose: Forwards a command payload for execution on a remote SSH endpoint.
Parameters:
- connectionId (string): Identifier matching a configured SSH profile.
- command (string): The operation to run remotely.
Output: Remote command output or an SSH failure report.
ssh_disconnect
Purpose: Gracefully terminates an active SSH session.
Parameter:
- connectionId (string): The target session ID.
Output: Status confirmation message.
create_ssh_connection
Purpose: Establishes a new remote connection profile dynamically.
Parameters:
- connectionId (string): Unique handle for the new session definition.
- connectionConfig (object): Details (host, credentials, ports).
Output: Success notification.
read_ssh_connections
Purpose: Fetches the complete inventory of currently defined SSH connection profiles.
Parameter: None.
Output: A collection structure detailing all known SSH endpoints.
update_ssh_connection
Purpose: Modifies parameters for an existing SSH session profile.
Parameters:
- connectionId (string): The profile identifier to modify.
- connectionConfig (object): The updated configuration data.
Output: Confirmation of update.
delete_ssh_connection
Purpose: Removes a defined SSH connection profile from memory.
Parameter:
- connectionId (string): The profile ID to erase.
Output: Confirmation of profile removal.
get_current_directory
Purpose: Reports the host service's current working path context.
Parameter: None.
Output: The absolute path string of the current directory.

System Resources

SSH Sessions Registry
URI Pattern: ssh://{connectionId}
Content: Metadata for individual SSH links, with sensitive credentials redacted (********).
Example Instance: ssh://raspberry-pi reveals its setup parameters.
Global SSH Parameters
URI: ssh://config
Content: Aggregate view of all SSH settings, including connection definitions (passwords masked).
Active Working Path
URI: cli://currentdir
Content: The active directory from which commands are launched.
Host Service Configuration
URI: cli://config
Content: The currently loaded configuration file data (excluding secrets).

Security Posture

Built-in Security Features (Immutable)

The following protective layers are hard-coded and operational regardless of configuration:

Case-Agnostic Blocking: Command and argument filtering operates without regard to casing (e.g., 'DEL.EXE' is filtered if 'del' is banned).
Path Sanitization: Comprehensive analysis of the full command path prevents attempts to execute blocked commands via their absolute paths.
Contextual Filtering: Logic designed to differentiate actual attack vectors from benign text within arguments.
Input Integrity Checks: Mandatory validation applied to all incoming data streams.
Process Lifecycle Management: Robust handling to ensure spawned processes are properly terminated post-execution or upon timeout.
Credential Obfuscation: Sensitive values (passwords, keys) are automatically obscured when exposed via Resource endpoints.

Configurable Security Features (Active by Default)

These safety mechanisms are enabled by default and can be modified in config.json:

Executable Blacklisting: Enforcement of the list defined in blockedCommands (e.g., system modification tools).
Parameter Blacklisting: Blockage of specific dangerous flags listed in blockedArguments.
Chaining Prevention: Defense against command concatenation (via enableInjectionProtection: true).
Directory Confinement: Enforcement that commands operate only within specified filesystem boundaries (via restrictWorkingDirectory: true).
Payload Size Cap: Limitation on maximum instruction length (default: 2000 characters).
Execution Watchdog: Automatic process termination after a set duration (default: 30 seconds).
Activity Auditing: Recording of all successful operations (logCommands: true).

Important Security Warnings

Users must remain aware of inherent risks:

Environment Variable Exposure: Executed processes inherit environment variables, which may contain confidential credentials or system paths.
Filesystem Reach: Commands within allowed paths have full read/write capabilities; allowedPaths must be severely limited to protect sensitive organizational data.

Licensing

Distributed under the terms of the MIT License (see LICENSE file for particulars).

WIKIPEDIA: The XMLHttpRequest (XHR) object is an Application Programming Interface within web browsers that facilitates asynchronous communication between the browser and a remote web server using HTTP protocols. This capability is foundational to asynchronous JavaScript and XML (Ajax) programming techniques. Before XHR, server interaction primarily involved full page reloads initiated by standard link clicks or form submissions.

win-cli-mcp-host-service

Author

simon-ami

Quick Info

Actions

Tags