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
• 🛡️ Path traversal prevention
• 🚫 Shell operator injection protection
• ⏱️ Execution timeouts and length limits
• 📝 Detailed error reporting
• 🔄 Async operation support

Configuration

Configure the server using environment variables:

| Variable | Description | Default | |----------------------|------------------------------------------|--------------------| | ALLOWED_DIR | Base directory for command execution | Required | | ALLOWED_COMMANDS | Comma-separated list of allowed commands | ls,cat,pwd | | ALLOWED_FLAGS | Comma-separated list of allowed flags | -l,-a,--help | | ALLOWED_PATTERNS | Comma-separated file patterns | *.txt,*.log,*.md | | MAX_COMMAND_LENGTH | Maximum command string length | 1024 | | COMMAND_TIMEOUT | Command execution timeout (seconds) | 30 |

Available Tools

run_command

Executes whitelisted CLI commands within allowed directories.

Input Schema:

{
 "command": {
   "type": "string",
   "description": "Command to execute (e.g., 'ls -l' or 'cat file.txt')"
 }
}

show_security_rules

Displays current security configuration and restrictions.

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",
       "ALLOWED_PATTERNS": "*.txt,*.log,*.md",
       "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",
        "ALLOWED_PATTERNS": "*.txt,*.log,*.md",
        "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
• ✅ Flag validation
• ✅ Path traversal prevention
• ✅ Shell operator blocking
• ✅ Command length limits
• ✅ Execution timeouts
• ✅ Working directory restrictions

Error Handling

The server provides detailed error messages for:

• Security violations
• Command timeouts
• Invalid command formats
• Path security violations
• Execution failures

Development

Prerequisites

• Python 3.10+
• MCP protocol library

Development

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.