mcp-shell

MCP-Server, der Shell-Befehle ausführt. Ihre LLM erhält ein Werkzeug; Sie behalten die Kontrolle darüber, was ausgeführt wird und wie.

Basiert auf mark3labs/mcp-go. Geschrieben in Go.

Ausführen

Docker (am einfachsten):

docker run -it --rm -v /tmp/mcp-workspace:/tmp/mcp-workspace sonirico/mcp-shell:latest

Aus dem Quellcode:

git clone https://github.com/sonirico/mcp-shell && cd mcp-shell
make install
mcp-shell

Related MCP server: MCP Shell Server

Konfigurieren

Der sichere Modus ist die Standardeinstellung. Ohne Konfigurationsdatei startet mcp-shell im sicheren Modus, der auf eine schmale Whitelist von schreibgeschützten Dienstprogrammen beschränkt ist (ls, cat, grep, find, head, tail, ...). Sie benötigen nur eine Konfigurationsdatei, um diese Richtlinie zu erweitern oder zu ändern. Um vollständig uneingeschränkt zu arbeiten, müssen Sie sich ausdrücklich dafür entscheiden:

MCP_SHELL_ALLOW_UNSAFE=true mcp-shell   # disables all validation - do not use in production

Um die Richtlinie anzupassen, verweisen Sie auf eine YAML-Konfiguration:

export MCP_SHELL_SEC_CONFIG_FILE=/path/to/security.yaml
mcp-shell

Sicherer Modus (empfohlen) — keine Shell-Interpretation, nur Whitelist für ausführbare Dateien:

security:
  enabled: true
  use_shell_execution: false
  allowed_executables:
    - ls
    - cat
    - grep
    - find
    - echo
  # WARNING: never add shell/language interpreters (bash, sh, python, perl,
  # ruby, node) or alias-capable tools (git) here - the interpreter executes
  # whatever it is handed, bypassing secure mode entirely. mcp-shell warns at
  # startup if it finds one.
  blocked_patterns:          # optional: restrict args on allowed commands
    - '(^|\s)remote\s+(-v|--verbose)(\s|$)'
  max_execution_time: 30s
  max_output_size: 1048576
  working_directory: /tmp/mcp-workspace
  audit_log: true

Legacy-Modus — Shell-Ausführung, Whitelist/Blacklist nach Befehlszeichenfolge (anfällig für Injection, wenn nicht vorsichtig):

security:
  enabled: true
  use_shell_execution: true
  allowed_commands: [ls, cat, grep, echo]
  blocked_patterns: ['rm\s+-rf', 'sudo\s+']
  max_execution_time: 30s
  audit_log: true

Einbinden

Claude Desktop — fügen Sie es zu Ihrer MCP-Konfiguration hinzu:

{
  "mcpServers": {
    "shell": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "sonirico/mcp-shell:latest"],
      "env": { "MCP_SHELL_LOG_LEVEL": "info" }
    }
  }
}

Für eine benutzerdefinierte Konfiguration mounten Sie die Datei und setzen Sie die Umgebungsvariable:

{
  "command": "docker",
  "args": ["run", "--rm", "-i", "-v", "/path/to/security.yaml:/etc/mcp-shell/security.yaml", "-e", "MCP_SHELL_SEC_CONFIG_FILE=/etc/mcp-shell/security.yaml", "sonirico/mcp-shell:latest"]
}

Tool-API

Die Antwort enthält status, exit_code, stdout, stderr, command, execution_time und optional security_info.

Umgebungsvariablen

Entwicklung

make install dev-tools   # deps + goimports, golines
make fmt test lint
make docker-build       # build image locally
make release            # binary + docker image

Sicherheit

• Standard: Sicherer Modus, beschränkt auf eine schmale Whitelist von schreibgeschützten Dienstprogrammen. Keine Interpreter.

• Sicherer Modus (use_shell_execution: false): Der Befehl wird in einen Shell-AST geparst und nur ein einzelner, vollständig literaler einfacher Befehl wird akzeptiert (keine Pipes, Listen, Substitution, Umleitung oder Globs); seine ausführbare Datei muss auf der Whitelist stehen. Interpreter (bash/sh/python) sind selbst dann hart abgelehnt, wenn sie auf der Whitelist stehen, und die Richtlinien pro Tool sind standardmäßig verweigernd: Für verwaltete Binärdateien (git, find, sort, tar) werden nur ausdrücklich sichere Flags akzeptiert, und alles andere, einschließlich unbekannter oder zukünftiger Escape-Flags, wird abgelehnt (git -c/config, find -exec/-fls, sort -o/--compress-program, tar -I/-C). Git ist auf schreibgeschützte Unterbefehle beschränkt. Dies ist eine frühe Ablehnungsschicht, kein Sandbox.

• Uneingeschränkt: Nur über MCP_SHELL_ALLOW_UNSAFE=true. Voller Zugriff; für lokale Entwicklung in Ordnung, sonst gefährlich.

• Docker: Läuft als Nicht-Root, basierend auf Alpine. Verwenden Sie es in der Produktion. Am besten in Kombination mit einer OS-Sandbox (schreibgeschütztes Dateisystem, entfernte Capabilities) als Defense-in-Depth.

Mitwirken

Forken, Branch erstellen, make fmt test ausführen, PR eröffnen.