CLI MCP Server

View original on GitHub 

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

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