Skip to main content
Glama
deenesjakoruzh
kg912

shell-mcp

by kg912
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

shell-mcp

Ein hochsicherer MCP-Server (Model Context Protocol) zum sicheren Ausführen von Shell-Befehlen mit einem lokalen LLM-Client.

Sicherheitsmodell

Befehle durchlaufen 8 unabhängige Sicherheitsebenen — jede einzelne muss bestanden werden:

Ebene

Funktion

1

Zod-Schema-Validierung — strikte Typenprüfung vor jeder Verarbeitung

2

Kein Shell-Spawn — execFile mit shell: false, niemals /bin/sh -c "..."

3

Fest codierte Blockliste — rm, sudo, dd, curl, brew, docker etc. dauerhaft blockiert

4

Argumentenprüfung — weist Metazeichen, Null-Bytes, verdächtige Muster und befehlsspezifische gefährliche Flags zurück

5

Verzeichnis-Allowlist — jeder Pfad muss innerhalb von --allow-dir liegen

6

Symlink-Auflösung — Symlinks werden vor der Pfadprüfung aufgelöst (kein Ausbruch via Symlink)

7

Ressourcenbeschränkungen — Timeout, Begrenzung der Ausgabegröße, Parallelitätslimit

8

Bereinigte Umgebung — entfernt AWS_*, *_TOKEN, *_SECRET und alle Cloud-Provider-Geheimnisse

Related MCP server: MCP Shell Server

Schnellstart

# Clone and build
git clone https://github.com/your-username/shell-mcp.git
cd shell-mcp
npm install
npm run build

# Run (must specify at least one --allow-dir)
node dist/index.js --allow-dir ~/projects --allow-dir ~/data

LLM-Client-Konfiguration

{
  "shell-mcp": {
    "command": "node",
    "args": [
      "/path/to/shell-mcp/dist/index.js",
      "--allow-dir", "/home/user/projects",
      "--allow-dir", "/home/user/data",
      "--allow-cmd", "ls",
      "--allow-cmd", "cat",
      "--allow-cmd", "grep",
      "--allow-cmd", "find",
      "--allow-cmd", "python3",
      "--timeout", "30",
      "--log-file", "/home/user/.shell-mcp/audit.log"
    ]
  }
}

Flags

Flag

Beschreibung

Standard

--allow-dir <path>

Erlaubtes Verzeichnis (erforderlich, wiederholbar)

keines — Server startet nicht

--allow-cmd <cmd>

Whitelist für spezifische Befehle (wiederholbar)

alle nicht blockierten

--block-cmd <cmd>

Zusätzliche zu blockierende Befehle

—

--timeout <secs>

Maximale Ausführungszeit (1–300)

30

--max-output <bytes>

Maximale Ausgabegröße

1048576 (1MB)

--max-concurrent <n>

Maximale parallele Befehle (1–10)

3

--log-file <path>

Pfad zur Audit-Log-Datei

nur stderr

--enable-write

Aktiviert das write_file-Tool

aus

--allow-overwrite

Erlaubt das Überschreiben von Dateien

aus

--read-only-mode

Deaktiviert alle Schreibvorgänge (überschreibt --enable-write)

aus

--allow-network-cmds

Entsperrt curl, wget, nc

aus

--allow-env-passthrough

Leitet die vollständige Umgebung an Kindprozesse weiter

aus (bereinigt)

Dem LLM bereitgestellte Tools

run_command

Führt einen Befehl mit einem expliziten Argumenten-Array aus. Keine Shell — Pipes und Umleitungen funktionieren nicht.

{
  "command": "grep",
  "args": ["-r", "TODO", "/home/user/projects/myapp"],
  "cwd": "/home/user/projects/myapp",
  "timeout": 10
}

read_file

Liest den Inhalt einer Datei. Unterstützt Zeilenbereiche und binäre (base64) Ausgabe.

{
  "path": "/home/user/projects/myapp/src/main.py",
  "startLine": 1,
  "endLine": 50
}

list_directory

Listet ein Verzeichnis mit Baumansicht, Größen und Berechtigungen auf.

{
  "path": "/home/user/projects/myapp",
  "recursive": true
}

write_file (erfordert --enable-write)

Schreibt eine Datei. Überschreibt nicht ohne --allow-overwrite.

{
  "path": "/home/user/projects/myapp/notes.txt",
  "content": "Hello world"
}

get_server_info

Gibt die aktuelle Serverkonfiguration und Einschränkungen zurück. Nützlich für das LLM, um seine Sandbox zu verstehen, bevor es agiert.

Dauerhaft blockierte Befehle

Diese können nicht durch Flags aktiviert werden:

rm, rmdir, shred, dd, mkfs, fdisk, diskutil, sudo, su, doas,
osascript, defaults, open, launchctl, crontab,
curl, wget, nc, ssh, scp, rsync,
brew, npm, yarn, pip, gem, cargo, docker,
gcc, clang, kill, killall, shutdown, reboot,
gpg, security (macOS keychain), ...and more

Audit-Log

Jeder Befehlsversuch (erlaubt oder verweigert) wird im JSON-Format protokolliert:

{"timestamp":"2024-01-01T12:00:00.000Z","sessionId":"A3F9B2C1","event":"COMMAND_DENY","command":"rm","args":["-rf","/"],"denyLayer":3,"denyReason":"Command \"rm\" is on the hardcoded blocklist"}
{"timestamp":"2024-01-01T12:00:01.000Z","sessionId":"A3F9B2C1","event":"COMMAND_ALLOW","command":"ls","args":["-la"],"cwd":"/home/user/projects","exitCode":0,"durationMs":12,"outputBytes":1024}

Überprüfung mit dem MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js --allow-dir /tmp/test

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Super Shell MCP Server

    cfdude
    A
    license
    A
    quality
    F
    maintenance
    An MCP server that enables secure execution of shell commands across Windows, macOS, and Linux with built-in whitelisting and approval mechanisms for enhanced security.
    9
    71 npm
    21
    MIT

  • MCP Shell Server

    fastmcp-me
    A
    license
    B
    quality
    D
    maintenance
    Enables secure execution of whitelisted shell commands through MCP, with support for stdin input, timeout control, and comprehensive output including stdout, stderr, and execution time.
    1
    MIT
  • terminal-toolkit-mcp by camel-ai

    terminal-toolkit-mcpofficial

    camel-ai
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables LLM clients to execute shell commands safely through the MCP protocol, with features like session management, safe mode, and process control.
    1
    Apache 2.0

  • Terminal MCP Server

    AcosX
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables executing shell commands on the host system via an MCP tool, with JWT/OAuth authentication and audit logging for secure remote access.
    1
    MIT