cli-mcp-server

# CLI MCP Server --- A secure Model Context Protocol (MCP) server implementation for executing controlled command-line operations with comprehensive security features.    [](https://smithery.ai/protocol/cli-mcp-server) [](https://github.com/MladenSU/cli-mcp-server/actions/workflows/python-tests.yml) <a href="https://glama.ai/mcp/servers/q89277vzl1"><img width="380" height="200" src="https://glama.ai/mcp/servers/q89277vzl1/badge" /></a> --- # Table of Contents 1. [Overview](#overview) 2. [Features](#features) 3. [Configuration](#configuration) 4. [Available Tools](#available-tools) - [run_command](#run_command) - [show_security_rules](#show_security_rules) 5. [Usage with Claude Desktop](#usage-with-claude-desktop) - [Development/Unpublished Servers Configuration](#developmentunpublished-servers-configuration) - [Published Servers Configuration](#published-servers-configuration) 6. [Security Features](#security-features) 7. [Error Handling](#error-handling) 8. [Development](#development) - [Prerequisites](#prerequisites) - [Building and Publishing](#building-and-publishing) - [Debugging](#debugging) 9. [License](#license) --- ## 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. ## 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 | |---------------------|------------------------------------------------------|-------------------| | `ALLOWED_DIR` | Base directory for command execution (Required) | None (Required) | | `ALLOWED_COMMANDS` | Comma-separated list of allowed commands or 'all' | `ls,cat,pwd` | | `ALLOWED_FLAGS` | Comma-separated list of allowed flags or 'all' | `-l,-a,--help` | | `MAX_COMMAND_LENGTH`| Maximum command string length | `1024` | | `COMMAND_TIMEOUT` | Command execution timeout (seconds) | `30` | | `ALLOW_SHELL_OPERATORS` | Allow shell operators (&&, \|\|, \|, >, etc.) | `false` | 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](https://smithery.ai/protocol/cli-mcp-server): ```bash npx @smithery/cli install cli-mcp-server --client claude ``` ## Available Tools ### run_command Executes whitelisted CLI commands within allowed directories. **Input Schema:** ```json { "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=true` - Commands 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 ```json { "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 ```json { "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: 1. Sync dependencies and update lockfile: ```bash uv sync ``` 2. Build package distributions: ```bash uv build ``` > This will create source and wheel distributions in the `dist/` directory. 3. Publish to PyPI: ```bash 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](https://github.com/modelcontextprotocol/inspector). You can launch the MCP Inspector via [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) with this command: ```bash npx @modelcontextprotocol/inspector uv --directory {{your source code local directory}}/cli-mcp-server run cli-mcp-server ``` Upon 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](LICENSE) file for details. --- For more information or support, please open an issue on the project repository.