📌Overview

Purpose: To provide a secure implementation of the Model Context Protocol (MCP) for executing controlled command-line operations with enhanced security.

Overview: The CLI MCP Server is designed to facilitate secure command-line execution by utilizing robust security features, such as command whitelisting, path validation, and execution controls. It is particularly useful for managing command-line access in large language model (LLM) applications while ensuring safety and reliability.

Key Features:

Secure Command Execution: Enforces strict validation to ensure that only authorized commands can be executed.
Configurable Whitelisting: Allows users to define a list of permissible commands and flags, with an option to permit all commands for flexibility.
Advanced Security Protections: Prevents path traversal, shell operator injection, and enforces execution timeouts, command length limits, and directory restrictions to maintain a secure operating environment.

CLI MCP Server

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

Overview
Features
Configuration
Available Tools
- run_command
- show_security_rules
Usage with Claude Desktop
- Development/Unpublished Servers Configuration
- Published Servers Configuration
Security Features
Error Handling
Development
- Prerequisites
- Building and Publishing
- Debugging
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`

Note: Setting ALLOWED_COMMANDS or ALLOWED_FLAGS to 'all' allows 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
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"
      }
    }
  }
}

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

If it is 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
✅ 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:

Sync dependencies and update lockfile:
```
uv sync
```
Build package distributions:
```
uv build
```
This creates source and wheel distributions in the dist/ directory.

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, it is recommended to use the MCP Inspector.

Launch the MCP Inspector via npm:

npx @modelcontextprotocol/inspector uv --directory {{your source code local directory}}/cli-mcp-server run cli-mcp-server

The Inspector will display a URL 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.

cli-mcp-server