MCPShell

MCPShell lets you safely expose shell-based tools to large language models through the Model Context Protocol (MCP). It provides a secure bridge that lets LLMs run predefined commands with parameter validation and optional sandboxing, enabling automated, controlled interactions with your system.

How to use

You will deploy a small configuration that defines the tools you want an LLM to run, then connect your MCP client to the local tool runner. Start by creating a YAML tool definition and then configure your MCP client to load that toolset. Once connected, you can ask the model to execute safe commands, inspect outputs, and format results for you.

A practical example defines a tool to analyze disk usage for a directory. The tool has an input parameter for the directory path and an optional max depth. It enforces security constraints to prevent unsafe paths and directory traversal, then executes a shell command that reports the top results.

Here is a minimal working configuration for the tool and a local runtime command you can use to start the MCP server. The tool is named disk_usage and is designed to be invoked by your MCP client through the MCP protocol.

yaml
mcp:
  description: |
    Tool for analyzing disk usage to help identify what's consuming space.
  run:
    shell: bash
  tools:
    - name: "disk_usage"
      description: "Check disk usage for a directory"
      params:
        directory:
          type: string
          description: "Directory to analyze"
          required: true
        max_depth:
          type: number
          description: "Maximum depth to analyze (1-3)"
          default: 2
      constraints:
        - "directory.startsWith('/')"  # Must be absolute path
        - "!directory.contains('..')"  # Prevent directory traversal
        - "max_depth >= 1 && max_depth <= 3"  # Limit recursion depth
        - "directory.matches('^[\\w\\s./\\-_]+$')"  # Safe path chars
      run:
        command: |
          du -h --max-depth={{ .max_depth }} {{ .directory }} | sort -hr | head -20
      output:
        prefix: |
          Disk Usage Analysis (Top 20 largest directories):

To run this locally, start an MCP-enabled runtime that serves the tools to your LLM client. The following example shows how to invoke MCPShell from the command line using Go, with a path to your tool configuration file and a log file for diagnostics.

{
  "mcpServers": {
    "mcp-cli-examples": {
      "command": "go",
      "args": [
        "run", "github.com/inercia/MCPShell@v0.1.8",
        "mcp", "--tools", "/my/example.yaml",
        "--logfile", "/some/path/mcpshell/example.log"
      ]
    }
  }
}

Available tools

disk_usage

Check disk usage for a directory