📌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, allowing controlled access to PowerShell, CMD, Git Bash shells, and remote systems via SSH. This server enables MCP clients to perform operations on your system securely.

IMPORTANT: This MCP server provides direct access to your system's command line interface. When enabled, it grants access to your files and command execution capabilities. Ensure to review and restrict allowed paths and SSH connections.

Table of 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 current directory and configuration as MCP resources.
• Security Controls:
  • Command and SSH command blocking
  • Working directory validation
  • Command logging and history tracking

Usage with Claude Desktop

Add this to your claude_desktop_config.json:

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

For use with a specific config file, the configuration looks like:

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

Configuration

The server uses a JSON configuration file for customizing its behavior. This includes settings for security controls, shell configurations, and SSH connections.

1. Create a default config file by copying config.json.example or running:

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

2. Set the --config flag to point to your config file.

Configuration Locations

The server looks for configurations in the following locations:

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

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

Default Configuration

The default configuration is designed to be restrictive and secure.

{
  "security": {
    "maxCommandLength": 2000,
    "blockedCommands": [...],
    "allowedPaths": ["User's home", "Current working directory"],
    "restrictWorkingDirectory": true,
    "logCommands": true,
    ...
  },
  "shells": {
    "powershell": {...},
    "cmd": {...},
    "gitbash": {...}
  },
  "ssh": {
    "enabled": false,
    ...
  }
}

Configuration Settings

The configuration file includes three main sections: security, shells, and ssh.

Security Settings

{
  "security": {
    "maxCommandLength": 1000,
    "blockedCommands": [...],
    "blockedArguments": [...],
    "allowedPaths": [...],
    "restrictWorkingDirectory": true,
    "logCommands": true,
    ...
  }
}

Shell Configuration

{
  "shells": {
    "powershell": {
      "enabled": true,
      ...
    },
    "cmd": {
      "enabled": true,
      ...
    },
    "gitbash": {
      "enabled": true,
      ...
    }
  }
}

SSH Configuration

{
  "ssh": {
    "enabled": false,
    ...
  }
}

API

Tools

• execute_command: Execute a command in the specified shell.
• get_command_history: Get the history of executed commands.
• ssh_execute: Execute a command on a remote system via SSH.
• create_ssh_connection: Create a new SSH connection.
• read_ssh_connections: Read all configured SSH connections.

Resources

• SSH Connections: Contains connection details.
• Current Directory: Current working directory of the server.
• CLI Configuration: Overall CLI server configuration.

Security Considerations

Built-in Security Features

• Case-insensitive command blocking
• Smart path parsing
• Input validation

Configurable Security Features

• Command blocking
• Argument blocking
• Working directory restriction

Important Security Warnings

• Commands may have access to sensitive environment variables and files. Configure allowedPaths carefully.

License

This project is licensed under the MIT License.