MCP HubMCP Hub
SimonB97

win-cli-mcp-server

by: SimonB97

Model Context Protocol server for secure command-line interactions on Windows systems

139created 04/12/2024
Visit
Windows
CLI

📌Overview

Purpose: The Windows CLI MCP Server facilitates secure command-line interactions on Windows systems, allowing controlled access to various shells and remote systems via SSH.

Overview: This framework serves as a Model Context Protocol (MCP) server that enables clients such as Claude Desktop to perform operations through command-line interfaces, ensuring that interactions are secure and permissions are effectively managed.

Key Features:

  • Multi-Shell Support: Execute commands in popular shell environments like PowerShell, Command Prompt (CMD), and Git Bash to provide versatility in command execution.

  • SSH Support: Execute commands on remote systems via SSH, enhancing remote management capabilities.

  • Resource Exposure: Provides visibility into SSH connections, current directory, and other configurations as MCP resources for client applications.

  • Security Controls: Implements robust security features including command and SSH command blocking, working directory validation, command length limits, command logging, and argument validation to mitigate risks and protect the system.

  • Configurable: Allows users to customize security rules, shell settings, SSH profiles, path restrictions, and command block lists to suit specific operational needs.

Windows CLI MCP Server

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

Important
This MCP server provides direct access to your system's command line and remote systems via SSH. When enabled, it grants access to your files, environment variables, command execution capabilities, and remote server management.

  • Review and restrict allowed paths and SSH connections
  • Enable directory restrictions
  • Configure command blocks
  • Consider security implications
    See Configuration for more details.

Contents

  • Features
  • Usage with Claude Desktop
  • Configuration
    • Configuration Locations
    • Default Configuration
    • Configuration Settings
      • Security Settings
      • Shell Configuration
      • SSH Configuration
  • API
    • Tools
    • Resources
  • Security Considerations
  • License

Features

  • Multi-Shell Support: Execute commands in PowerShell, Command Prompt (CMD), and Git Bash
  • SSH Support: Execute commands on remote systems via SSH
  • Resource Exposure: View SSH connections, current directory, and configuration as MCP resources
  • Security Controls:
    • Command and SSH command blocking (full paths, case variations)
    • Working directory validation
    • Maximum command length limits
    • Command logging and history tracking
    • Smart argument validation
  • Configurable:
    • Custom security rules
    • Shell-specific settings
    • SSH connection profiles
    • Path restrictions
    • Blocked command lists

The server only allows operations within configured directories, with allowed commands, and on configured SSH connections.

Usage with Claude Desktop

Add the following to your claude_desktop_config.json:

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

To use a specific config file, add the --config flag:

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

After configuring, you can:

  • Execute commands using the available tools
  • View configured SSH connections and server configuration in the Resources section
  • Manage SSH connections through the provided tools

Configuration

The server uses a JSON configuration file for customization including security, shell, and SSH settings.

Getting Started

  1. Create a default config file by either:
    • Copying config.json.example to config.json
    • Running:
    npx @simonb97/server-win-cli --init-config ./config.json
  2. Use the --config flag to specify your config file when launching the server.

Configuration Locations

The server searches for a config file in order:

  1. Path specified by --config flag
  2. ./config.json in the current directory
  3. ~/.win-cli-mcp/config.json in the user's home directory

If none found, a default restrictive configuration is used.

Default Configuration

The default config is secure and restrictive. Key settings include:

{
  "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 config file includes three main sections: security, shells, and ssh.

Security Settings

{
  "security": {
    "maxCommandLength": 1000,
    "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": ["C:\\Users\\YourUsername", "C:\\Projects"],
    "restrictWorkingDirectory": true,
    "logCommands": true,
    "maxHistorySize": 1000,
    "commandTimeout": 30,
    "enableInjectionProtection": true
  }
}

Shell Configuration

{
  "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 Configuration

{
  "ssh": {
    "enabled": false,
    "defaultTimeout": 30,
    "maxConcurrentSessions": 5,
    "keepaliveInterval": 10000,
    "keepaliveCountMax": 3,
    "readyTimeout": 20000,
    "connections": {
      "raspberry-pi": {
        "host": "raspberrypi.local",
        "port": 22,
        "username": "pi",
        "password": "raspberry",
        "keepaliveInterval": 10000,
        "keepaliveCountMax": 3,
        "readyTimeout": 20000
      },
      "dev-server": {
        "host": "dev.example.com",
        "port": 22,
        "username": "admin",
        "privateKeyPath": "C:\\Users\\YourUsername\\.ssh\\id_rsa",
        "keepaliveInterval": 10000,
        "keepaliveCountMax": 3,
        "readyTimeout": 20000
      }
    }
  }
}

API

Tools

  • execute_command
    Execute a command in a specified shell.
    Inputs:

    • shell: "powershell", "cmd", or "gitbash"
    • command: Command to execute
    • workingDir (optional): Working directory path
      Returns command output or error message.

  • get_command_history
    Retrieve history of executed commands.
    Input: limit (optional)
    Returns timestamped command history with outputs.

  • ssh_execute
    Execute a command on a remote system via SSH.
    Inputs:

    • connectionId: SSH connection ID
    • command: Command to execute
      Returns output or error.

  • ssh_disconnect
    Disconnect SSH connection.
    Input: connectionId
    Returns confirmation.

  • create_ssh_connection
    Create new SSH connection.
    Inputs:

    • connectionId
    • connectionConfig: Object with host, port, username, password or privateKeyPath
      Returns confirmation.

  • read_ssh_connections
    Retrieve all SSH connections from config.

  • update_ssh_connection
    Update existing SSH connection.
    Inputs:

    • connectionId, connectionConfig
      Returns confirmation.

  • delete_ssh_connection
    Delete an SSH connection.
    Input: connectionId
    Returns confirmation.

  • get_current_directory
    Get current working directory of the server.

Resources

  • SSH Connections
    URI format: ssh://{connectionId}
    Each resource shows connection details with sensitive info masked.

  • SSH Configuration
    URI: ssh://config
    Overall SSH config and connections with passwords masked.

  • Current Directory
    URI: cli://currentdir
    Shows default command execution directory.

  • CLI Configuration
    URI: cli://config
    Shows server configuration excluding sensitive data.

Security Considerations

Built-in Security Features (Always Active)

  • Case-insensitive command blocking
  • Smart path parsing to prevent bypasses
  • Intelligent command parsing to avoid false positives
  • Input validation before execution
  • Proper shell process management
  • Sensitive data masking in resources

Configurable Security Features (Active by Default)

  • Command and argument blocking
  • Command injection protection
  • Working directory restriction
  • Command length limit
  • Command timeout
  • Command logging

Important Security Notes

  • Commands have access to environment variables, possibly containing sensitive data
  • Commands can read/write files within allowed paths — carefully configure allowedPaths

License

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