shell-mcp

A super-secure MCP (Model Context Protocol) server for running shell commands safely with a local LLM client.

Security Model

Commands pass through 8 independent security layers — every one must pass:

Layer	What it does
1	Zod schema validation — strict type checks before any processing
2	No-shell spawn — execFile with shell: false, no /bin/sh -c "..." ever
3	Hardcoded blocklist — rm, sudo, dd, curl, brew, docker, etc. permanently blocked
4	Argument inspection — rejects metacharacters, null bytes, suspicious patterns, per-command dangerous flags
5	Directory allowlist — every path must be inside --allow-dir
6	Symlink resolution — symlinks resolved before path check (no escape via symlink)
7	Resource limits — timeout, output size cap, concurrency limit
8	Sanitized environment — strips AWS_*, *_TOKEN, *_SECRET, all cloud provider secrets

Quick Start

# 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 Configuration

{
  "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	Description	Default
--allow-dir <path>	Permitted directory (required, repeatable)	none — server won't start
--allow-cmd <cmd>	Whitelist specific commands (repeatable)	all non-blocked
--block-cmd <cmd>	Extra commands to block	—
--timeout <secs>	Max execution time (1–300)	30
--max-output <bytes>	Max output size	1048576 (1MB)
--max-concurrent <n>	Max parallel commands (1–10)	3
--log-file <path>	Audit log file path	stderr only
--enable-write	Enable write_file tool	off
--allow-overwrite	Permit overwriting files	off
--read-only-mode	Disables all writes (overrides --enable-write)	off
--allow-network-cmds	Unblock curl, wget, nc	off
--allow-env-passthrough	Forward full env to child processes	off (sanitized)

Tools Exposed to the LLM

run_command

Run a command with explicit arguments array. No shell — pipes and redirects won't work.

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

read_file

Read a file's contents. Supports line ranges and binary (base64) output.

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

list_directory

List a directory with tree view, sizes, and permissions.

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

write_file (requires --enable-write)

Write a file. Won't overwrite without --allow-overwrite.

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

get_server_info

Returns current server config and restrictions. Useful for the LLM to understand its sandbox before acting.

Permanently Blocked Commands

These cannot be enabled by any flag:

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

Every command attempt (allowed or denied) is logged in JSON:

{"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}

Inspect with MCP Inspector

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