Summary of the changes:

Added Output Sanitization Function:

Created a new sanitize_output() function that:

Removes ANSI escape sequences (colors, cursor movements, etc.) Filters out control characters that could disrupt the interface Limits the output size to prevent buffer overflows Adds a clear message when output is truncated

Modified Command Response Handling:

Updated the handle_call_tool() function to sanitize stdout and stderr before sending to Claude Desktop Applied sanitization to both standard output and error streams

Preserved Shell Operator Functionality:

Kept the shell=True flag to maintain support for &&, |, and other shell operators Ensured all command chaining capabilities remain intact

Added Proper Documentation:

Included detailed docstrings for the new function Explained the purpose of the sanitization

Changes Made to Fix the Freezing Issue

Adaptive Timeouts Based on Command Complexity:

Simple commands (like ls, chmod, pwd) now use a 3-second timeout Medium complexity commands use a 10-second timeout Complex commands use the original default timeout (30 seconds)

Command Classification System:

Added a classify_command_complexity function that intelligently categorizes commands Detects shell operators like pipes, redirections, and chains to determine complexity

Improved Error Handling:

Enhanced timeout error messages with more helpful suggestions Better logging of command execution times and errors

Logging System:

Added comprehensive logging to track command execution times Logs command classification, execution time, and any errors Helps diagnose problems without interfering with the interface

Performance Optimizations:

Quick commands now respond nearly instantly Added timing tracking to identify slow operations

These changes should prevent Claude Desktop from freezing on simple commands while still allowing complex operations to work properly with shell operators like && and |.

Version 0.2.2 fixed the issue where the server would freeze when handling error responses, with a complete overhaul of the error handling system. Version 0.2.3 added log rotation, and version 0.2.4 dramatically reduces log volume by filtering MCP framework logs.

Key improvements:

• Never Freezes on Errors: The server now handles all error conditions gracefully, never returning null responses that could cause the interface to freeze
• Extended Exception System: Added error result objects to exceptions that provide structured error data
• Failsafe Response Construction: Every response path now has multiple layers of validation to ensure at least one valid text item is returned
• Improved Sanitization: Enhanced output sanitization to handle a wider variety of edge cases
• Robust Command Execution: Better handling of command timeouts and execution failures
• Optimized Logging System: Logs are now rotated (max 1MB per file, 3 backup files) to prevent excessive disk usage
• Framework Log Filtering: MCP framework logs are filtered to CRITICAL level only to dramatically reduce log volume
• Configurable Log Levels: Set verbosity with the LOG_LEVEL environment variable (defaults to ERROR for minimal logging)

A secure Model Context Protocol (MCP) server implementation for executing controlled command-line operations with comprehensive security features.

1. Overview
2. Features
3. Configuration
4. Available Tools
   • run_command
   • show_security_rules
5. Usage with Claude Desktop
   • Development/Unpublished Servers Configuration
   • Published Servers Configuration
6. Security Features
7. Error Handling
8. Development
   • Prerequisites
   • Building and Publishing
   • Debugging
9. License

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.

• 🔒 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

Configure the server using environment variables:

Note: Setting ALLOWED_COMMANDS or ALLOWED_FLAGS to 'all' will allow any command or flag respectively.

To install CLI MCP Server for Claude Desktop automatically via Smithery:

npx @smithery/cli install cli-mcp-server --client claude

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
• 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

Displays current security configuration and restrictions, including:

• Working directory
• Allowed commands
• Allowed flags
• Security limits (max command length and timeout)

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"
      }
    }
  }
}

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"
      }
    }
  }
}

In case it's not working or showing in the UI, clear your cache via uv clean.

• ✅ Command whitelist enforcement with 'all' option
• ✅ Flag validation with 'all' option
• ✅ Path traversal prevention and normalization
• ✅ Shell operator blocking
• ✅ Command length limits
• ✅ Execution timeouts
• ✅ Working directory restrictions
• ✅ Symlink resolution and validation

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)

• Python 3.10+
• MCP protocol library

To prepare the package for distribution:

1. Sync dependencies and update lockfile:

   uv sync

2. Build package distributions:

   uv build

   This will create source and wheel distributions in the dist/ directory.

3. Publish to PyPI:

   uv publish --token {{YOUR_PYPI_API_TOKEN}}

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-server

Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.

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.