Overview

CLI MCP Server enables AI assistants to execute command-line operations in a secure, controlled environment. It implements the Model Context Protocol (MCP) to provide a safe interface between AI models and your system's command line.

Key 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

Installation

Automatic Installation via Smithery

The easiest way to install CLI MCP Server for Claude Desktop is via Smithery:

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

Manual Installation

1. Install the package using pip:

pip install cli-mcp-server

2. Configure the server using environment variables (see Configuration section below).

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 |

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

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
• 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 the server configuration to your Claude Desktop config file located at: ~/Library/Application Support/Claude/claude_desktop_config.json

For Development/Unpublished Servers:

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

For Published Servers:

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

If the server isn't showing in the UI, try clearing your cache via uv clean.

Security Features

CLI MCP Server implements multiple layers of security:

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

Error Handling

The server provides detailed error messages for various scenarios:

• Security violations (CommandSecurityError)
• Command timeouts (CommandTimeoutError)
• Invalid command formats
• Path security violations
• Execution failures (CommandExecutionError)
• General command errors (CommandError)

These error messages help diagnose issues while maintaining security.