MCPShell MCP Server for Secure LLM Command Execution

Overview

MCPShell is an MCP (Model Context Protocol) server that lets large language models execute controlled command-line tools. It translates declarative tool definitions into safe, auditable shell invocations so an LLM can query system state or run read-only OS commands without unrestricted shell access. MCPShell is intended for developers who want to expose specific CLI capabilities to an LLM client (Cursor, VSCode, etc.) while enforcing parameter validation and execution constraints.

The server uses YAML tool manifests to describe each tool’s parameters, validations (CEL expressions), and the actual command templates. Optional sandboxed runners and strict constraint checks reduce risk from malicious prompts or parameter injection, making MCPShell suitable for diagnostics, monitoring, and other read-only automation tasks.

Features

• Flexible shell-based tools implemented via templates (bash, sh, etc.).
• Declarative YAML tool definitions: params, defaults, descriptions.
• Parameter validation using CEL expressions to prevent unsafe inputs.
• Optional sandboxed runner support to constrain runtime environments.
• Output formatting options (prefixes, post-processing) to help LLMs interpret results.
• Works with any MCP-compatible client (Cursor, VSCode, other LLM frontends).
• Audit logging of requests and executions for traceability.

Installation / Configuration

Quick steps to run MCPShell locally (requires Go):

1. Create a tools YAML file (example below).
2. Start the MCP server using go run or by building the binary.
3. Configure your MCP-capable LLM client to start the server.

Example tool definition (disk usage analyzer):

mcp:
  description: Toolset to analyze disk usage and report the largest directories.
  run:
    shell: bash
tools:
  - name: disk_usage
    description: "List top directories by size for an absolute path"
    params:
      directory:
        type: string
        description: "Absolute directory path"
        required: true
      max_depth:
        type: number
        description: "Max depth (1-3)"
        default: 2
    constraints:
      - "directory.startsWith('/')"
      - "!directory.contains('..')"
      - "max_depth >= 1 && max_depth <= 3"
      - "directory.matches('^[\\w\\s./\\-_]+$')"
    run:
      command: |
        du -h --max-depth={{ .max_depth }} {{ .directory }} | sort -hr | head -n 20
    output:
      prefix: "Disk Usage Analysis (Top 20):"

Start via Go (example):

go run github.com/inercia/MCPShell@latest mcp --tools /path/to/tools.yaml --logfile /var/log/mcpshell.log

Example Cursor client configuration to launch the MCP server:

{
  "mcpServers": {
    "mcpshell-example": {
      "command": "go",
      "args": [
        "run",
        "github.com/inercia/[email protected]",
        "mcp",
        "--tools", "/my/example.yaml",
        "--logfile", "/tmp/mcpshell/example.log"
      ]
    }
  }
}

Paths can be relative; the server will look up tool files in its configured tools directory by default.

Configuration schema (key fields)

Available Resources

• GitHub repository: https://github.com/inercia/mcpshell
• Examples directory: multiple YAML examples (kubectl read-only, AWS CLI read-only, etc.)
• Documentation:
  • Configuration schema and runners (docs/config.md, docs/config-runners.md)
  • Usage and command reference (docs/usage.md)
  • Cursor and VSCode integration guides (docs/usage-cursor.md, docs/usage-vscode.md)
  • Container and Kubernetes deployment guide (docs/usage-containers.md)
  • Security considerations and best practices (docs/security.md)
  • Development and contributing guide (docs/development.md)
• Related project (Agent mode): Don — an agent that can use MCPShell tool configs for direct LLM-to-tool connections.

Use Cases

• Disk inspection: Allow an LLM to summarize disk usage without write/delete access (the disk_usage example above).
• Kubernetes read-only diagnostics: Provide kubectl wrappers that run safe, read-only cluster queries (get, describe) with parameter checks to avoid destructive commands.
• Cloud account auditing: Expose restricted AWS CLI queries (IAM listings, networking diagnostics) with constraints to prevent resource modification.
• Log analysis: Tail and filter logs from specific directories, constrained to safe file paths and size limits.
• Development helpers: Run unit-test summaries or static analyzers (read-only outputs) so an LLM can recommend fixes.

Concrete example: Letting a model find large files

• Tool: disk_usage (above)
• User prompt to the LLM: “Find the largest directories under /var and suggest which can be cleaned.”
• MCPShell validates the directory is absolute and contains only safe characters, runs the command, and returns the formatted top-20 output to the LLM for further reasoning.

Security guidance

• Prefer read-only tools; avoid exposing destructive operations (delete, move, write).
• Rigorously use constraints (CEL) to validate inputs and prevent path traversal or command injection.
• Consider sandboxed runners (chroot, containers) for additional isolation.
• Review every command template for injection vectors and log all invocations for auditing.
• Read docs/security.md before exposing MCPShell to untrusted models or users.

MCPShell is designed to make it practical and safer to bridge LLMs and shell tools, but responsible configuration and strict constraints are essential.