CLI

You can run a secure command-line execution service that exposes whitelisted CLI operations to your applications. This MCP server enforces strict security rules, validates commands and flags, prevents path traversal, and caps execution time, giving you controlled, async-capable access to shell commands from your models or automations.

How to use

You use an MCP client to connect to the CLI MCP Server and request the execution of approved commands. Your client will send a command string and the server will return the result or an error. You can rely on the server to enforce the command whitelist, flag restrictions, and directory rules, ensuring that only permitted actions run within the designated base directory.

How to install

Prerequisites you need before installing the CLI MCP Server: Python 3.10 or newer, and access to a runtime capable of running MCP servers (MCP protocol library). You also need a client or tooling to install the server integration described here.

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

Additional configuration and operation notes

Configure the server with environment variables to define the allowed working directory, commands, flags, and timeouts. Two example configurations are shown for development and published server usage.

{
  "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,--version",
        "MAX_COMMAND_LENGTH": "1024",
        "COMMAND_TIMEOUT": "30"
      }
    }
  }
}

Security tips and troubleshooting

This server enforces a command whitelist, validates flags, prevents path traversal, blocks shell operators, enforces maximum command length, and applies execution timeouts. If an error occurs, you’ll receive a detailed message describing the security violation, timeout, invalid format, path issue, or execution failure.

Developer notes

For development and debugging, run in environments that expose the MCP protocol and consider using the MCP Inspector for interactive debugging. The inspector provides a browser-based interface to observe and step through MCP commands and responses.

Notes on publishing and runtime

When you are ready to publish or run locally, build the package, then start the server using the runtime command provided in your setup. If you see issues in the UI, clearing the cache can help.

Available tools

run_command

Executes whitelisted CLI commands within allowed directories. Accepts a command string and returns the output or an error if the command is not allowed or fails.

show_security_rules

Displays the current security configuration, including allowed commands, flags, and path rules.