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:

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",
        "/cli-mcp-server",
        "run",
        "cli-mcp-server"
      ],
      "env": {
        "ALLOWED_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": "",
        "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](https://docs.npmjs.com/downloading-and-installing-node-js-and-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.