Windows CLI

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

[!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

- Windows CLI MCP Server (Enhanced)

- Features
- Usage with Claude Desktop

- Configuration Setup

- Configuration Structure
- Configuration Locations
- Default Configuration
- Configuration Settings

- Global Settings

- Security Settings
- Restriction Settings
- Path Settings

- Basic Shell Configuration
- Shell-Specific Overrides
- WSL Configuration

- Built-in Security Features
- Configurable Security Features (Active by Default)
- Best Practices

- Prerequisites
- Getting Started
- Running Tests in the Dev Container

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

A companion VS Code extension invscode-extension/simplifies configuring this server. It exposes every CLI option as ordinary VS Code settings (scoped perUserand perWorkspace) and registers the MCP server with VS Code automatically via the MCP Server Definition Provider API — no hand-editedmcp.jsonrequired. It can also generate aconfig.jsonor a.vscode/mcp.jsonon demand. Seevscode-extension/README.md.

# Full build (all shells) - default npm run build # Windows-only shells (PowerShell, CMD, Git Bash) npm run build:windows # Git Bash only (smallest Windows build) npm run build:gitbash # CMD only npm run build:cmd # Unix/Linux only (Bash) npm run build:unix # Custom combination INCLUDED_SHELLS=gitbash,powershell npm run build:custom

- Architecture Overview- System design and module structure
- User Guide- How to build and use specialized versions
- API Documentation- Complete API reference for shell plugins
- Migration Guide- Upgrading from previous versions
- Testing Guide- Testing strategies for modular shells

# Build npm run build:gitbash # Use in Claude Desktop config { "mcpServers": { "windows-cli": { "command": "node", "args": ["/path/to/wcli0/dist/index.gitbash-only.js"] } } }

While wcli0 is primarily designed for Windows, it also supports Unix-based systems (macOS, Linux) with Bash shell integration.

To build wcli0 for Unix-based systems (macOS, Linux):

# Unix-only build (Bash shell) npm run build:unix # The output will be: dist/index.unix-only.js

# Start with default settings npx wcli0 --shell bash # Start with a configuration file npx wcli0 --config ./config.mac.json # Start with specific allowed directories npx wcli0 --shell bash \ --allowedDir "/Users/$(whoami)" \ --allowedDir "/tmp"

Here's a sample configuration for macOS:

{ "global": { "security": { "commandTimeout": 30, "enableInjectionProtection": true, "restrictWorkingDirectory": true }, "restrictions": { "blockedCommands": ["rm -rf /", "dd", "mkfs"], "blockedArguments": ["--force", "-rf"], "blockedOperators": ["&&", "||", ";", "|"] }, "paths": { "allowedPaths": ["/Users/$(whoami)", "/tmp"], "initialDir": "/Users/$(whoami)" } }, "shells": { "bash_auto": { "type": "bash_auto", "enabled": true } } }

Configure Claude Desktop to use wcli0 on macOS:

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

- Path Formats: Unix systems use forward slashes (/) and do not support Windows drive letters
- Shell Type: Usebashorbash_autoshell types on Unix systems
- Home Directory: Use$(whoami)or your actual username in paths
- Security Commands: Some blocked commands in the default configuration are Windows-specific (e.g.,regedit,format)

When running on Unix systems, use these CLI options:

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

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

- File-based storage: WhenlogDirectoryis configured, logs are saved to files for persistent storage
- In-memory storage: Default behavior using MCP log resources (e.g.,cli://logs/commands/{id})
- Theget_command_outputtool (fallback for hosts that cannot read resources)

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

For persistent logging, configure a log directory:

{ "global": { "logging": { "logDirectory": "./logs", "exposeFullPath": false } } }

npx wcli0 --shell gitbash --logDirectory ./logs

- Truncation messages show the file path directly (simpler output)
- Logs persist across server restarts
- No in-memory storage limits apply
- Starting the server with--debugautomatically enables file-based logging to your OS temp directory (<temp>/wcli0-debug-logs) when nologDirectoryis set, so every command and its output are persisted during debugging sessions.

Security Note: Log files may contain sensitive command output. Ensure the log directory has appropriate permissions.

Access stored command output via MCP resources (in-memory mode):

- 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

SeeAPI Documentationfor detailed resource specifications and query parameters.

{ "global": { "logging": { "maxOutputLines": 20, "enableTruncation": true, "maxStoredLogs": 50, "maxLogSize": 1048576, "enableLogResources": true, "logRetentionMinutes": 1440, "logDirectory": "./logs" } } }

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

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

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

- Copyconfig.examples/config.sample.jsonfor basic setup
- Copyconfig.examples/config.development.jsonfor development environments
- Copyconfig.examples/config.secure.jsonfor high-security environments
- Copyconfig.examples/emptyRestrictions.jsonto remove all default restrictions

# 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--initialDirflag 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 configure output truncation and logging via CLI:

npx wcli0 --shell gitbash \ --maxOutputLines 50 \ --enableTruncation \ --enableLogResources \ --maxReturnLines 1000 \ --logDirectory ./logs

When--logDirectoryis configured, command output logs are saved to files instead of in-memory storage. Truncation messages will show the file path for easy access to full output.

Security Note: Log files may contain sensitive data from command output. Ensure the log directory has appropriate permissions and consider implementing log rotation.

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:

When started this way,restrictWorkingDirectoryis forced on andenableInjectionProtectionis disabled to ensure the allowed paths apply without shell injection checks.

If you need to disable safety checks that block command execution for experimentation, you can start the server inunsafeorYOLOmodes (not recommended for production):

# YOLO disables all safety checks except allowed working directories npx wcli0 --yolo # Fully unsafe removes all safety checks, including directory limits npx wcli0 --unsafe

Both modes clear blocked commands/arguments/operators and turn off injection protection. YOLO mode leaves working directory restrictions active, while fully unsafe mode disables those restrictions as well. These two flags are mutually exclusive; using both at once will fail.

You can start the server with an HTTP-based transport instead of the default stdio transport, so remote and web-based MCP clients can connect over HTTP. Two HTTP transports are available:

-

http-- the modernStreamable HTTPtransport (MCP protocol revision 2025-03-26), serving a single/mcpendpoint. This is what current MCP clients default to and is the recommended HTTP transport.

sse-- the legacyHTTP+SSEtransport (MCP protocol revision 2024-11-05), using two endpoints (GET /sse,POST /messages). It is deprecated by the MCP spec in favor of Streamable HTTP and is kept only for compatibility with older clients.

The modes are mutually exclusive (selected by--transport) and use separate bind settings (--http-forhttp,--sse-forsse).

# Streamable HTTP on the default host/port (127.0.0.1:9444), serving /mcp npx wcli0 --transport http # Custom port, still bound to localhost npx wcli0 --transport http --http-host 127.0.0.1 --http-port 3000 # Legacy HTTP+SSE transport npx wcli0 --transport sse --sse-host 127.0.0.1 --sse-port 3000

Whenhttpmode is active, clients use a single/mcpendpoint:

POST /mcpcarries client-to-server JSON-RPC messages. Aninitializerequest with no session id starts a new session; the server returns the assigned id in theMcp-Session-Idresponse header, and the client must send that header on every subsequent request.

GET /mcpopens the optional server-to-client SSE stream for an existing session.

DELETE /mcpterminates an existing session.