Skip to content
Back to search

win-cli-mcp-server

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/simon-ami--win-cli-mcp-server/badge.svg)](/listings/simon-ami--win-cli-mcp-server)

HTML

<a href="/listings/simon-ami--win-cli-mcp-server"><img src="/api/listings/simon-ami--win-cli-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 463 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Windows CLI MCP Server
  2. > [!CAUTION]
  3. > **PROJECT DEPRECATED** - No longer maintained.
  4. > Use https://github.com/wonderwhy-er/DesktopCommanderMCP instead for similar functionality.
  5. [![NPM Downloads](https://img.shields.io/npm/dt/@simonb97/server-win-cli.svg?style=flat)](https://www.npmjs.com/package/@simonb97/server-win-cli)
  6. [![NPM Version](https://img.shields.io/npm/v/@simonb97/server-win-cli.svg?style=flat)](https://www.npmjs.com/package/@simonb97/server-win-cli?activeTab=versions)
  7. [![smithery badge](https://smithery.ai/badge/@simonb97/server-win-cli)](https://smithery.ai/server/@simonb97/server-win-cli)
  8. [MCP server](https://modelcontextprotocol.io/introduction) 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](https://claude.ai/download)) to perform operations on your system, similar to [Open Interpreter](https://github.com/OpenInterpreter/open-interpreter).
  9. >[!IMPORTANT]
  10. > This MCP server provides direct access to your system's command line interface and remote systems via SSH. When enabled, it grants access to your files, environment variables, command execution capabilities, and remote server management.
  11. >
  12. > - Review and restrict allowed paths and SSH connections
  13. > - Enable directory restrictions
  14. > - Configure command blocks
  15. > - Consider security implications
  16. >
  17. > See [Configuration](#configuration) for more details.
  18. - [Features](#features)
  19. - [Usage with Claude Desktop](#usage-with-claude-desktop)
  20. - [Configuration](#configuration)
  21. - [Configuration Locations](#configuration-locations)
  22. - [Default Configuration](#default-configuration)
  23. - [Configuration Settings](#configuration-settings)
  24. - [Security Settings](#security-settings)
  25. - [Shell Configuration](#shell-configuration)
  26. - [SSH Configuration](#ssh-configuration)
  27. - [API](#api)
  28. - [Tools](#tools)
  29. - [Resources](#resources)
  30. - [Security Considerations](#security-considerations)
  31. - [License](#license)
  32. ## Features
  33. - **Multi-Shell Support**: Execute commands in PowerShell, Command Prompt (CMD), and Git Bash
  34. - **SSH Support**: Execute commands on remote systems via SSH
  35. - **Resource Exposure**: View SSH connections, current directory, and configuration as MCP resources
  36. - **Security Controls**:
  37. - Command and SSH command blocking (full paths, case variations)
  38. - Working directory validation
  39. - Maximum command length limits
  40. - Command logging and history tracking
  41. - Smart argument validation
  42. - **Configurable**:
  43. - Custom security rules
  44. - Shell-specific settings
  45. - SSH connection profiles
  46. - Path restrictions
  47. - Blocked command lists
  48. See the [API](#api) section for more details on the tools and resources the server provides to MCP clients.
  49. **Note**: The server will only allow operations within configured directories, with allowed commands, and on configured SSH connections.
  50. ## Usage with Claude Desktop
  51. Add this to your `claude_desktop_config.json`:
  52. ```json
  53. {
  54. "mcpServers": {
  55. "windows-cli": {
  56. "command": "npx",
  57. "args": ["-y", "@simonb97/server-win-cli"]
  58. }
  59. }
  60. }
  61. ```
  62. For use with a specific config file, add the `--config` flag:
  63. ```json
  64. {
  65. "mcpServers": {
  66. "windows-cli": {
  67. "command": "npx",
  68. "args": [
  69. "-y",
  70. "@simonb97/server-win-cli",
  71. "--config",
  72. "path/to/your/config.json"
  73. ]
  74. }
  75. }
  76. }
  77. ```
  78. After configuring, you can:
  79. - Execute commands directly using the available tools
  80. - View configured SSH connections and server configuration in the Resources section
  81. - Manage SSH connections through the provided tools
  82. ## Configuration
  83. The server uses a JSON configuration file to customize its behavior. You can specify settings for security controls, shell configurations, and SSH connections.
  84. 1. To create a default config file, either:
  85. **a)** copy `config.json.example` to `config.json`, or
  86. **b)** run:
  87. ```bash
  88. npx @simonb97/server-win-cli --init-config ./config.json
  89. ```
  90. 2. Then set the `--config` flag to point to your config file as described in the [Usage with Claude Desktop](#usage-with-claude-desktop) section.
  91. ### Configuration Locations
  92. The server looks for configuration in the following locations (in order):
  93. 1. Path specified by `--config` flag
  94. 2. ./config.json in current directory
  95. 3. ~/.win-cli-mcp/config.json in user's home directory
  96. If no configuration file is found, the server will use a default (restricted) configuration:
  97. ### Default Configuration
  98. **Note**: The default configuration is designed to be restrictive and secure. Find more details on each setting in the [Configuration Settings](#configuration-settings) section.
  99. ```json
  100. {
  101. "security": {
  102. "maxCommandLength": 2000,
  103. "blockedCommands": [
  104. "rm",
  105. "del",
  106. "rmdir",
  107. "format",
  108. "shutdown",
  109. "restart",
  110. "reg",
  111. "regedit",
  112. "net",
  113. "netsh",
  114. "takeown",
  115. "icacls"
  116. ],
  117. "blockedArguments": [
  118. "--exec",
  119. "-e",
  120. "/c",
  121. "-enc",
  122. "-encodedcommand",
  123. "-command",
  124. "--interactive",
  125. "-i",
  126. "--login",
  127. "--system"
  128. ],
  129. "allowedPaths": ["User's home directory", "Current working directory"],
  130. "restrictWorkingDirectory": true,
  131. "logCommands": true,
  132. "maxHistorySize": 1000,
  133. "commandTimeout": 30,
  134. "enableInjectionProtection": true
  135. },
  136. "shells": {
  137. "powershell": {
  138. "enabled": true,
  139. "command": "powershell.exe",
  140. "args": ["-NoProfile", "-NonInteractive", "-Command"],
  141. "blockedOperators": ["&", "|", ";", "`"]
  142. },
  143. "cmd": {
  144. "enabled": true,
  145. "command": "cmd.exe",
  146. "args": ["/c"],
  147. "blockedOperators": ["&", "|", ";", "`"]
  148. },
  149. "gitbash": {
  150. "enabled": true,
  151. "command": "C:\\Program Files\\Git\\bin\\bash.exe",
  152. "args": ["-c"],
  153. "blockedOperators": ["&", "|", ";", "`"]
  154. }
  155. },
  156. "ssh": {
  157. "enabled": false,
  158. "defaultTimeout": 30,
  159. "maxConcurrentSessions": 5,
  160. "keepaliveInterval": 10000,
  161. "keepaliveCountMax": 3,
  162. "readyTimeout": 20000,
  163. "connections": {}
  164. }
  165. }
  166. ```
  167. ### Configuration Settings
  168. The configuration file is divided into three main sections: `security`, `shells`, and `ssh`.
  169. #### Security Settings
  170. ```json
  171. {
  172. "security": {
  173. // Maximum allowed length for any command
  174. "maxCommandLength": 1000,
  175. // Commands to block - blocks both direct use and full paths
  176. // Example: "rm" blocks both "rm" and "C:\\Windows\\System32\\rm.exe"
  177. // Case-insensitive: "del" blocks "DEL.EXE", "del.cmd", etc.
  178. "blockedCommands": [
  179. "rm", // Delete files
  180. "del", // Delete files
  181. "rmdir", // Delete directories
  182. "format", // Format disks
  183. "shutdown", // Shutdown system
  184. "restart", // Restart system
  185. "reg", // Registry editor
  186. "regedit", // Registry editor
  187. "net", // Network commands
  188. "netsh", // Network commands
  189. "takeown", // Take ownership of files
  190. "icacls" // Change file permissions
  191. ],
  192. // Arguments that will be blocked when used with any command
  193. // Note: Checks each argument independently - "cd warm_dir" won't be blocked just because "rm" is in blockedCommands
  194. "blockedArguments": [
  195. "--exec", // Execution flags
  196. "-e", // Short execution flags
  197. "/c", // Command execution in some shells
  198. "-enc", // PowerShell encoded commands
  199. "-encodedcommand", // PowerShell encoded commands
  200. "-command", // Direct PowerShell command execution
  201. "--interactive", // Interactive mode which might bypass restrictions
  202. "-i", // Short form of interactive
  203. "--login", // Login shells might have different permissions
  204. "--system" // System level operations
  205. ],
  206. // List of directories where commands can be executed
  207. "allowedPaths": ["C:\\Users\\YourUsername", "C:\\Projects"],
  208. // If true, commands can only run in allowedPaths
  209. "restrictWorkingDirectory": true,
  210. // If true, saves command history
  211. "logCommands": true,
  212. // Maximum number of commands to keep in history
  213. "maxHistorySize": 1000,
  214. // Timeout for command execution in seconds (default: 30)
  215. "commandTimeout": 30,
  216. // Enable or disable protection against command injection (covers ;, &, |, \`)
  217. "enableInjectionProtection": true
  218. }
  219. }
  220. ```
  221. #### Shell Configuration
  222. ```json
  223. {
  224. "shells": {
  225. "powershell": {
  226. // Enable/disable this shell
  227. "enabled": true,
  228. // Path to shell executable
  229. "command": "powershell.exe",
  230. // Default arguments for the shell
  231. "args": ["-NoProfile", "-NonInteractive", "-Command"],
  232. // Optional: Specify which command operators to block
  233. "blockedOperators": ["&", "|", ";", "`"] // Block all command chaining
  234. },
  235. "cmd": {
  236. "enabled": true,
  237. "command": "cmd.exe",
  238. "args": ["/c"],
  239. "blockedOperators": ["&", "|", ";", "`"] // Block all command chaining
  240. },
  241. "gitbash": {
  242. "enabled": true,
  243. "command": "C:\\Program Files\\Git\\bin\\bash.exe",
  244. "args": ["-c"],
  245. "blockedOperators": ["&", "|", ";", "`"] // Block all command chaining
  246. }
  247. }
  248. }
  249. ```
  250. #### SSH Configuration
  251. ```json
  252. {
  253. "ssh": {
  254. // Enable/disable SSH functionality
  255. "enabled": false,
  256. // Default timeout for SSH commands in seconds
  257. "defaultTimeout": 30,
  258. // Maximum number of concurrent SSH sessions
  259. "maxConcurrentSessions": 5,
  260. // Interval for sending keepalive packets (in milliseconds)
  261. "keepaliveInterval": 10000,
  262. // Maximum number of failed keepalive attempts before disconnecting
  263. "keepaliveCountMax": 3,
  264. // Timeout for establishing SSH connections (in milliseconds)
  265. "readyTimeout": 20000,
  266. // SSH connection profiles
  267. "connections": {
  268. // NOTE: these examples are not set in the default config!
  269. // Example: Local Raspberry Pi
  270. "raspberry-pi": {
  271. "host": "raspberrypi.local", // Hostname or IP address
  272. "port": 22, // SSH port
  273. "username": "pi", // SSH username
  274. "password": "raspberry", // Password authentication (if not using key)
  275. "keepaliveInterval": 10000, // Override global keepaliveInterval
  276. "keepaliveCountMax": 3, // Override global keepaliveCountMax
  277. "readyTimeout": 20000 // Override global readyTimeout
  278. },
  279. // Example: Remote server with key authentication
  280. "dev-server": {
  281. "host": "dev.example.com",
  282. "port": 22,
  283. "username": "admin",
  284. "privateKeyPath": "C:\\Users\\YourUsername\\.ssh\\id_rsa", // Path to private key
  285. "keepaliveInterval": 10000,
  286. "keepaliveCountMax": 3,
  287. "readyTimeout": 20000
  288. }
  289. }
  290. }
  291. }
  292. ```
  293. ## API
  294. ### Tools
  295. - **execute_command**
  296. - Execute a command in the specified shell
  297. - Inputs:
  298. - `shell` (string): Shell to use ("powershell", "cmd", or "gitbash")
  299. - `command` (string): Command to execute
  300. - `workingDir` (optional string): Working directory
  301. - Returns command output as text, or error message if execution fails
  302. - **get_command_history**
  303. - Get the history of executed commands
  304. - Input: `limit` (optional number)
  305. - Returns timestamped command history with outputs
  306. - **ssh_execute**
  307. - Execute a command on a remote system via SSH
  308. - Inputs:
  309. - `connectionId` (string): ID of the SSH connection to use
  310. - `command` (string): Command to execute
  311. - Returns command output as text, or error message if execution fails
  312. - **ssh_disconnect**
  313. - Disconnect from an SSH server
  314. - Input:
  315. - `connectionId` (string): ID of the SSH connection to disconnect
  316. - Returns confirmation message
  317. - **create_ssh_connection**
  318. - Create a new SSH connection
  319. - Inputs:
  320. - `connectionId` (string): ID for the new SSH connection
  321. - `connectionConfig` (object): Connection configuration details including host, port, username, and either password or privateKeyPath
  322. - Returns confirmation message
  323. - **read_ssh_connections**
  324. - Read all configured SSH connections
  325. - Returns a list of all SSH connections from the configuration
  326. - **update_ssh_connection**
  327. - Update an existing SSH connection
  328. - Inputs:
  329. - `connectionId` (string): ID of the SSH connection to update
  330. - `connectionConfig` (object): New connection configuration details
  331. - Returns confirmation message
  332. - **delete_ssh_connection**
  333. - Delete an SSH connection
  334. - Input:
  335. - `connectionId` (string): ID of the SSH connection to delete
  336. - Returns confirmation message
  337. - **get_current_directory**
  338. - Get the current working directory of the server
  339. - Returns the current working directory path
  340. ### Resources
  341. - **SSH Connections**
  342. - URI format: `ssh://{connectionId}`
  343. - Contains connection details with sensitive information masked
  344. - One resource for each configured SSH connection
  345. - Example: `ssh://raspberry-pi` shows configuration for the "raspberry-pi" connection
  346. - **SSH Configuration**
  347. - URI: `ssh://config`
  348. - Contains overall SSH configuration and all connections (with passwords masked)
  349. - Shows settings like defaultTimeout, maxConcurrentSessions, and the list of connections
  350. - **Current Directory**
  351. - URI: `cli://currentdir`
  352. - Contains the current working directory of the CLI server
  353. - Shows the path where commands will execute by default
  354. - **CLI Configuration**
  355. - URI: `cli://config`
  356. - Contains the CLI server configuration (excluding sensitive data)
  357. - Shows security settings, shell configurations, and SSH settings
  358. ## Security Considerations
  359. ### Built-in Security Features (Always Active)
  360. The following security features are hard-coded into the server and cannot be disabled:
  361. - **Case-insensitive command blocking**: All command blocking is case-insensitive (e.g., "DEL.EXE", "del.cmd", etc. are all blocked if "del" is in blockedCommands)
  362. - **Smart path parsing**: The server parses full command paths to prevent bypass attempts (blocking "C:\\Windows\\System32\\rm.exe" if "rm" is blocked)
  363. - **Command parsing intelligence**: False positives are avoided (e.g., "warm_dir" is not blocked just because "rm" is in blockedCommands)
  364. - **Input validation**: All user inputs are validated before execution
  365. - **Shell process management**: Processes are properly terminated after execution or timeout
  366. - **Sensitive data masking**: Passwords are automatically masked in resources (replaced with ********)
  367. ### Configurable Security Features (Active by Default)
  368. These security features are configurable through the config.json file:
  369. - **Command blocking**: Commands specified in `blockedCommands` array are blocked (default includes dangerous commands like rm, del, format)
  370. - **Argument blocking**: Arguments specified in `blockedArguments` array are blocked (default includes potentially dangerous flags)
  371. - **Command injection protection**: Prevents command chaining (enabled by default through `enableInjectionProtection: true`)
  372. - **Working directory restriction**: Limits command execution to specified directories (enabled by default through `restrictWorkingDirectory: true`)
  373. - **Command length limit**: Restricts maximum command length (default: 2000 characters)
  374. - **Command timeout**: Terminates commands that run too long (default: 30 seconds)
  375. - **Command logging**: Records command history (enabled by default through `logCommands: true`)
  376. ### Important Security Warnings
  377. These are not features but important security considerations to be aware of:
  378. - **Environment access**: Commands may have access to environment variables, which could contain sensitive information
  379. - **File system access**: Commands can read/write files within allowed paths - carefully configure `allowedPaths` to prevent access to sensitive data
  380. ## License
  381. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.