cli-mcp-server

GitHub
  • OS Automation
Python
MIT
10
A
security – no known vulnerabilities (report Issue)
A
license - permissive license (MIT)
A
quality - confirmed to work

Command line interface with secure execution and customizable security policies

  1. Tools
  2. Prompts
  3. Resources
  4. Server Configuration
  5. README.md

Prompts

Interactive templates invoked by user choice

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

Tools

Functions exposed to the LLM to take actions

NameDescription
run_commandAllows command (CLI) execution in the directory: /app Available commands: pwd, ls, cat Available flags: -l, --help, -a Note: Shell operators (&&, |, >, >>) are not supported.
show_security_rulesShow what commands and operations are allowed in this environment.

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
ALLOWED_DIRYesBase directory for command execution
ALLOWED_FLAGSNoComma-separated list of allowed flags-l,-a,--help
COMMAND_TIMEOUTNoCommand execution timeout (seconds)30
ALLOWED_COMMANDSNoComma-separated list of allowed commandsls,cat,pwd
ALLOWED_PATTERNSNoComma-separated file patterns*.txt,*.log,*.md
MAX_COMMAND_LENGTHNoMaximum command string length1024
Need Help?View Source CodeReport Issue
README.md

CLI MCP Server

A secure Model Context Protocol (MCP) server implementation for executing controlled command-line operations with comprehensive security features.

License Python Version MCP Protocol smithery badge

<a href="https://glama.ai/mcp/servers/q89277vzl1"><img width="380" height="200" src="https://glama.ai/mcp/servers/q89277vzl1/badge" /></a>

Table of Contents

  1. Overview
  2. Features
  3. Configuration
  4. Available Tools
  5. Usage with Claude Desktop
  6. Security Features
  7. Error Handling
  8. Development
  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:

VariableDescriptionDefault
ALLOWED_DIRBase directory for command executionRequired
ALLOWED_COMMANDSComma-separated list of allowed commandsls,cat,pwd
ALLOWED_FLAGSComma-separated list of allowed flags-l,-a,--help
MAX_COMMAND_LENGTHMaximum command string length1024
COMMAND_TIMEOUTCommand execution timeout (seconds)30

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": "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", "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
  • ✅ 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.

GitHub Badge

Glama performs regular codebase and documentation scans to:

  • Confirm that the MCP server is working as expected.
  • Confirm that there are no obvious security issues with dependencies of the server.
  • Extract server characteristics such as tools, resources, prompts, and required parameters.

Our directory badge helps users to quickly asses that the MCP server is safe, server capabilities, and instructions for installing the server.

Copy the following code to your README.md file:

Alternative MCP servers

  • mcp-nodejs-server

    -
    security
    A
    license
    -
    quality
    MCP Server for the Gentoro services, enabling Claude to interact with Gentoro, which allows users to create and integrate tools into a common Bridge, defining all available capabilities.
    Apache-2.0