cli-mcp-server
The cli-mcp-server provides secure execution of whitelisted command-line operations within a restricted environment.
Execute CLI commands: Run whitelisted commands (
pwd,cat,echo,find,ls,grep) with allowed flags (-l,-h,--help,-v,-a,-r) within the restricted/appdirectory.View security rules: Check the current security configuration, including allowed commands, flags, and operational restrictions.
Secure execution: Enforces strict validation of commands and flags while preventing shell operators (e.g.,
&&,|,>) by default.Controlled environment: All operations are constrained within the
/appdirectory, preventing unauthorized access.
Allows execution of whitelisted shell commands with comprehensive security features including command and flag whitelisting, path validation, and protection against injection attacks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cli-mcp-server show me what files are in the current directory"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
CLI MCP Server
A secure Model Context Protocol (MCP) server implementation for executing controlled command-line operations with comprehensive security features.
Table of Contents
Overview
This MCP server enables secure command-line execution with robust security measures including command whitelisting, path validation, and execution controls. Perfect for providing controlled CLI access to LLM applications while maintaining security.
Related MCP server: Windows CLI MCP Server
Features
🔒 Secure command execution with strict validation
⚙️ Configurable command and flag whitelisting with 'all' option
🛡️ Path traversal prevention and validation
🚫 Shell operator injection protection
⏱️ Execution timeouts and length limits
📝 Detailed error reporting
🔄 Async operation support
🎯 Working directory restriction and validation
Configuration
Configure the server using environment variables:
Variable | Description | Default |
| Base directory for command execution (Required) | None (Required) |
| Comma-separated list of allowed commands or 'all' |
|
| Comma-separated list of allowed flags or 'all' |
|
| Maximum command string length |
|
| Command execution timeout (seconds) |
|
| Allow shell operators (&&, ||, |, >, etc.) |
|
Note: Setting ALLOWED_COMMANDS or ALLOWED_FLAGS to 'all' will allow any command or flag respectively.
Installation
To install CLI MCP Server for Claude Desktop automatically via Smithery:
npx @smithery/cli install cli-mcp-server --client claudeAvailable Tools
run_command
Executes whitelisted CLI commands within allowed directories.
Input Schema:
{
"command": {
"type": "string",
"description": "Single command to execute (e.g., 'ls -l' or 'cat file.txt')"
}
}Security Notes:
Shell operators (&&, |, >, >>) are not supported by default, but can be enabled with
ALLOW_SHELL_OPERATORS=trueCommands must be whitelisted unless ALLOWED_COMMANDS='all'
Flags must be whitelisted unless ALLOWED_FLAGS='all'
All paths are validated to be within ALLOWED_DIR
show_security_rules
Displays current security configuration and restrictions, including:
Working directory
Allowed commands
Allowed flags
Security limits (max command length and timeout)
Usage with Claude Desktop
Add to your ~/Library/Application\ Support/Claude/claude_desktop_config.json:
Development/Unpublished Servers Configuration
{
"mcpServers": {
"cli-mcp-server": {
"command": "uv",
"args": [
"--directory",
"<path/to/the/repo>/cli-mcp-server",
"run",
"cli-mcp-server"
],
"env": {
"ALLOWED_DIR": "</your/desired/dir>",
"ALLOWED_COMMANDS": "ls,cat,pwd,echo",
"ALLOWED_FLAGS": "-l,-a,--help,--version",
"MAX_COMMAND_LENGTH": "1024",
"COMMAND_TIMEOUT": "30",
"ALLOW_SHELL_OPERATORS": "false"
}
}
}
}Published Servers Configuration
{
"mcpServers": {
"cli-mcp-server": {
"command": "uvx",
"args": [
"cli-mcp-server"
],
"env": {
"ALLOWED_DIR": "</your/desired/dir>",
"ALLOWED_COMMANDS": "ls,cat,pwd,echo",
"ALLOWED_FLAGS": "-l,-a,--help,--version",
"MAX_COMMAND_LENGTH": "1024",
"COMMAND_TIMEOUT": "30",
"ALLOW_SHELL_OPERATORS": "false"
}
}
}
}In case it's not working or showing in the UI, clear your cache via
uv clean.
Security Features
✅ Command whitelist enforcement with 'all' option
✅ Flag validation with 'all' option
✅ Path traversal prevention and normalization
✅ Shell operator blocking (with opt-in support via
ALLOW_SHELL_OPERATORS=true)✅ Command length limits
✅ Execution timeouts
✅ Working directory restrictions
✅ Symlink resolution and validation
Error Handling
The server provides detailed error messages for:
Security violations (CommandSecurityError)
Command timeouts (CommandTimeoutError)
Invalid command formats
Path security violations
Execution failures (CommandExecutionError)
General command errors (CommandError)
Development
Prerequisites
Python 3.10+
MCP protocol library
Building and Publishing
To prepare the package for distribution:
Sync dependencies and update lockfile:
uv syncBuild package distributions:
uv buildThis will create source and wheel distributions in the
dist/directory.Publish to PyPI:
uv publish --token {{YOUR_PYPI_API_TOKEN}}
Debugging
Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we strongly recommend using the MCP Inspector.
You can launch the MCP Inspector via npm with
this command:
npx @modelcontextprotocol/inspector uv --directory {{your source code local directory}}/cli-mcp-server run cli-mcp-serverUpon launching, the Inspector will display a URL that you can access in your browser to begin debugging.
License
This project is licensed under the MIT License - see the LICENSE file for details.
For more information or support, please open an issue on the project repository.
Available Tools
2 toolsrun_commandA
Allows command (CLI) execution in the directory: /app
Available commands: pwd, ls, cat Available flags: -l, --help, -a
Shell operators (&&, ||, |, >, >>, <, <<, ;) are not supported. Set ALLOW_SHELL_OPERATORS=true to enable.
Inputs: command (required).
show_security_rulesB
Show what commands and operations are allowed in this environment.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools have completely distinct purposes: run_command executes CLI commands with specific constraints, while show_security_rules displays allowed operations and permissions. There is no overlap or ambiguity between these functions.
Both tools follow a clear verb_noun pattern (run_command, show_security_rules), which is consistent and readable. The minor deviation is that 'run' and 'show' are different verbs, but this is appropriate given their distinct actions.
With only 2 tools, the server feels thin for a CLI server that presumably handles command execution and environment management. A typical CLI server would benefit from more tools (e.g., for file operations, process management, or configuration), making this count insufficient for the apparent scope.
The tool surface is severely incomplete for a CLI server. It lacks basic operations like file creation, deletion, editing, process monitoring, or environment configuration. The run_command tool is limited to a few commands, and there are no tools for managing the CLI environment beyond showing security rules, creating significant gaps for agent workflows.
Maintenance
Related MCP Connectors
Scoped agent execution. Server-side credentials, policy, budgets and verifiable receipts.
Security gateway for AI agents: policy, approval, and audited execution, no secrets shared.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Remote MCP for Android CLI agent build gate, structured receipts, audit logs, and reviewer-ready evi
Related MCP Servers
- FlicenseBqualityDmaintenanceEnables safe execution of system shell commands with real-time streaming output and rich metadata capture. Provides configurable command execution with timeout controls, environment management, and extensible plugin architecture for monitoring command lifecycles.4-
- AlicenseAqualityCmaintenanceEnables secure command-line interactions on Windows systems with support for PowerShell, CMD, Git Bash, and WSL shells, providing controlled file access, command execution, and configurable security restrictions.625 npm4MIT
- AlicenseNot gradedqualityCmaintenanceProvides a secure environment for executing shell commands with restricted directory access and timeout enforcement. It includes tools for running commands, managing execution history, and isolating environment variables.24 npmMIT
- FlicenseNot gradedqualityDmaintenanceA security-focused tool that implements least-privilege credential injection for Claude Code by intercepting Bash and MCP tool calls to swap in minimum-privilege tokens. It enables secure execution of CLI commands and MCP operations by matching tool arguments against declarative YAML policies to prevent unauthorized access.-