CLI MCP Server

A secure MCP server for controlled command-line operations.

View on GitHub

155

Stars

Forks

155

Watchers

Issues

CLI MCP Server provides a secure implementation of the Model Context Protocol (MCP) for executing command-line operations with robust security features. It enables controlled CLI access by enforcing command and flag whitelisting, path validation, and shell operator restrictions, making it suitable for integration with large language model applications. Designed for configurable deployment, it supports detailed error reporting, execution timeouts, and strict working directory controls.

Key Features

Strict command whitelisting

Flag whitelisting with optional 'all' mode

Path traversal protection

Shell operator injection prevention

Execution timeouts and output length limits

Configurable environment variables

Detailed error reporting

Async operation support

Working directory restriction

Current security configuration inspection

Use Cases

Providing secure CLI access for LLM-based agents or applications

Automating server maintenance routines with strict controls

Allowing safe, remote CLI execution in a sandboxed environment

Integrating controlled shell command execution with external ML workflows

Preventing unauthorized or risky shell operations in user-facing tools

Facilitating system administration via secure model context handoffs

Maintaining auditable, restricted access to sensitive filesystem paths

Production or development use in AI desktop clients like Claude Desktop

Enabling AI supervision for infrastructure automation

Validating user commands within constrained computing environments

README

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

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:

bash

npx @smithery/cli install cli-mcp-server --client claude

Available Tools

run_command

Executes whitelisted CLI commands within allowed directories.

Input Schema:

json

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

json

{
  "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",
        "ALLOW_SHELL_OPERATORS": "false"
      }
    }
  }
}

Published Servers Configuration

json

{
  "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",
        "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:

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

Publish to PyPI:

bash

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:

bash

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.

Star History

Repository Owner

MladenSU

User

Repository Details

Language Python

Default Branch main

Size 61 KB

Contributors 4

License MIT License

MCP Verified Nov 11, 2025

Programming Languages

Python

100%

Related MCPs

Discover similar Model Context Protocol servers

MCP Shell Server

A secure, configurable shell command execution server implementing the Model Context Protocol.

MCP Shell Server provides secure remote execution of whitelisted shell commands via the Model Context Protocol (MCP). It supports standard input, command output retrieval, and enforces strict safety checks on command operations. The tool allows configuration of allowed commands and execution timeouts, and can be integrated with platforms such as Claude.app and Smithery. With robust security assessments and flexible deployment methods, it facilitates controlled shell access for AI agents.

⭐ 153
MCP
tumf/mcp-shell-server

mcp-shell

A secure Model Context Protocol (MCP) server for AI-driven shell command execution.

mcp-shell enables AI assistants and MCP clients to securely execute shell commands via the standardized Model Context Protocol. Built in Go and leveraging the official MCP SDK, it facilitates structured, auditable, and context-aware access to shell environments. The server emphasizes security through Docker isolation, command validation, resource limits, and comprehensive audit logging.

⭐ 44
MCP
sonirico/mcp-shell

SSH MCP Server

MCP-compliant SSH server for secure command execution on Linux and Windows.

SSH MCP Server provides an MCP-compliant interface to expose SSH control for both Linux and Windows systems. It enables secure execution of shell commands remotely, supporting password and SSH key authentication as well as sudo and su elevation. Built with TypeScript and the official MCP SDK, the server offers configurable timeouts, process management, and compatibility with popular LLM clients such as Claude Desktop and Cursor. Designed for robust and flexible integration, it facilitates natural language interfaces to system administration tasks.

⭐ 137
MCP
tufantunc/ssh-mcp

mcp-cli

A command-line inspector and client for the Model Context Protocol

mcp-cli is a command-line interface tool designed to interact with Model Context Protocol (MCP) servers. It allows users to run and connect to MCP servers from various sources, inspect available tools, resources, and prompts, and execute commands non-interactively or interactively. The tool supports OAuth for various server types, making integration and automation seamless for developers working with MCP-compliant servers.

⭐ 391
MCP
wong2/mcp-cli

CMD MCP Server

Execute CMD commands via the Model Context Protocol with cross-platform and SSH support.

CMD MCP Server is an implementation of the Model Context Protocol (MCP) for executing CMD commands on Windows and Linux systems, with additional support for SSH connections. It enables seamless integration of command-line operations with MCP-compatible applications, leveraging the official MCP SDK. Written in TypeScript for cross-platform compatibility, it allows programmatic execution, configuration, and extension of CMD operations through standardized protocols. The server is designed for easy installation, robust configuration, and developer-friendly extension.

⭐ 22
MCP
PhialsBasement/CMD-MCP-Server

just-mcp

A production-ready MCP server for Justfile command integration with LLMs.

just-mcp delivers an MCP (Model Context Protocol) server that enables seamless integration between AI assistants and the Just command runner. It provides functionality for AI models to discover, execute, and introspect Justfile recipes using a standardized protocol. The system emphasizes context abstraction, safer command execution compared to raw bash, and user-friendly interfaces for both agents and humans. Built-in safety and validation features further enhance reliability and security.

⭐ 31
MCP
PromptExecution/just-mcp

View all Alternatives

Didn't find tool you were looking for?

Search AI Tools

CLI MCP Server

Key Features

Use Cases

README

CLI MCP Server

Table of Contents

Overview

Features

Configuration

Installation

Available Tools

run_command

show_security_rules

Usage with Claude Desktop

Security Features

Error Handling

Development

Prerequisites

Building and Publishing

Debugging

License

Star History

Repository Owner

Repository Details

Programming Languages

Tags

Related MCPs