CLI MCP Server

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

Table of Contents

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

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:

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

Available 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=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

{
  "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:

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

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-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 file for details.

For more information or support, please open an issue on the project repository.