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
• 🌐 HTTP/HTTPS proxy support for network commands
• 📏 Configurable output length limits with truncation
• 🔧 Robust configuration with error handling and fallbacks

Configuration

Configure the server using environment variables:

Basic Security Configuration

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
ALLOW_SHELL_OPERATORS	Allow shell operators (&&, ||, |, >, etc.)	false

Output Control Configuration

Variable	Description	Default
MAX_OUTPUT_LENGTH	Maximum total output length (characters)	10240
MAX_STDOUT_LENGTH	Maximum stdout length (characters)	8192
MAX_STDERR_LENGTH	Maximum stderr length (characters)	2048
OUTPUT_TRUNCATE_MESSAGE	Message shown when output is truncated	...[output truncated]

Proxy Configuration

Variable	Description	Default
CLI_PROXY_ENABLED	Enable proxy support for HTTP/HTTPS requests	false
CLI_PROXY_URL	Proxy URL (also checks HTTP_PROXY if not set)	None

Proxy Usage Examples:

# Enable proxy with custom URL
CLI_PROXY_ENABLED=true
CLI_PROXY_URL=http://proxy.company.com:8080

# Or use standard HTTP_PROXY environment variable
CLI_PROXY_ENABLED=true
HTTP_PROXY=http://proxy.company.com:8080

Output Control Examples:

# Limit stdout to 4KB and stderr to 1KB
MAX_STDOUT_LENGTH=4096
MAX_STDERR_LENGTH=1024
OUTPUT_TRUNCATE_MESSAGE="... [Output truncated due to length limit]"

# Disable output limiting (set to very large values)
MAX_STDOUT_LENGTH=1000000
MAX_STDERR_LENGTH=1000000

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

Common Use Cases

Corporate Environment with Proxy

# Enable proxy for all HTTP/HTTPS commands like curl, wget
CLI_PROXY_ENABLED=true
CLI_PROXY_URL=http://proxy.corporate.com:8080
ALLOWED_COMMANDS=ls,cat,pwd,curl,wget
ALLOWED_FLAGS=all

Limited Output for Performance

# Prevent memory issues with large command outputs
MAX_STDOUT_LENGTH=4096
MAX_STDERR_LENGTH=1024
OUTPUT_TRUNCATE_MESSAGE="... [Output limited for performance]"

Development Environment

# Allow most commands but limit output size
ALLOWED_COMMANDS=all
ALLOWED_FLAGS=all
ALLOW_SHELL_OPERATORS=true
MAX_STDOUT_LENGTH=16384
CLI_PROXY_ENABLED=true

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)
• Output length limits
• Proxy configuration status

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,curl",
        "ALLOWED_FLAGS": "-l,-a,--help,--version,-s,-G",
        "MAX_COMMAND_LENGTH": "1024",
        "COMMAND_TIMEOUT": "30",
        "ALLOW_SHELL_OPERATORS": "false",
        "MAX_STDOUT_LENGTH": "8192",
        "MAX_STDERR_LENGTH": "2048",
        "CLI_PROXY_ENABLED": "false",
        "CLI_PROXY_URL": "http://proxy.company.com:8080",
        "OUTPUT_TRUNCATE_MESSAGE": "...[output truncated]"
      }
    }
  }
}

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,curl",
        "ALLOWED_FLAGS": "-l,-a,--help,--version,-s,-G",
        "MAX_COMMAND_LENGTH": "1024",
        "COMMAND_TIMEOUT": "30",
        "ALLOW_SHELL_OPERATORS": "false",
        "MAX_STDOUT_LENGTH": "8192",
        "MAX_STDERR_LENGTH": "2048",
        "CLI_PROXY_ENABLED": "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
• ✅ Output length limiting with configurable truncation
• ✅ Robust environment variable validation with fallbacks
• ✅ Proxy support with secure environment variable handling

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.