Purpose
cli-mcp-server is a secure MCP (Model Context Protocol) server implementation used to perform controlled command-line operations. It provides a command-line interface for MCP clients (such as Claude Desktop), enabling LLM applications to run CLI commands under strict security policies. It is suitable for scenarios that need to expose controlled CLI access to LLM applications while maintaining security boundaries.
Main Capabilities
- Available tools: run_command (executes whitelisted commands within allowed directories), show_security_rules (displays the current security configuration and restrictions).
- Security features: command whitelist, with support for the 'all' option; argument (flag) whitelist, with support for the 'all' option; path traversal protection and normalization; shell operator injection protection (&&, |, >, >> are not supported by default and can be enabled via ALLOW_SHELL_OPERATORS=true); command length limits; execution timeout; working directory restrictions and validation; symlink resolution and validation.
- Supports asynchronous operations.
- Provides detailed error information, including: security violations (CommandSecurityError), command timeout (CommandTimeoutError), invalid command format, path security violations, execution failure (CommandExecutionError), and general command errors (CommandError).
- The server is configured through environment variables. Setting ALLOWED_COMMANDS or ALLOWED_FLAGS to 'all' will allow any command or argument, respectively.
Usage
- With Claude Desktop: add the configuration to ~/Library/Application Support/Claude/claude_desktop_config.json. If it does not take effect or does not appear in the interface, you can clear the cache with uv clean.
- CLI MCP Server can be automatically installed for Claude Desktop via Smithery.
- Development and release: sync dependencies and update the lockfile using uv sync; build the package using uv build, which will generate the source package and wheel package in the dist/ directory; publish to PyPI using uv publish --token {{YOUR_PYPI_API_TOKEN}}.
- Debugging: because the MCP server runs over stdio, debugging can be difficult. The official recommendation is to use MCP Inspector, which can be started via an npm command; after startup, Inspector will display a URL that can be accessed in a browser to begin debugging.
Applicable Scenarios
Scenarios that need to provide controlled command-line capabilities for LLM applications, for example executing operations within restricted directories and the scope of whitelisted commands, while also expecting security controls such as path validation, timeout, and length limits.
Limitations
- Shell operators are not supported by default and must be explicitly enabled via ALLOW_SHELL_OPERATORS=true.
- Commands must be in the whitelist unless ALLOWED_COMMANDS='all'; arguments must be in the whitelist unless ALLOWED_FLAGS='all'.
- All paths will be validated to ensure they are within ALLOWED_DIR.
- This project uses the MIT license.
- The materials do not provide specific pricing, charging methods, supported platform scope, or performance metrics.
- For more information or support, please submit an issue in the project repository.
