Skip to main content
Glama
deenesjakoruzh
kg912

shell-mcp

by kg912
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

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

This server cannot be installed

F
license - not found
-
quality - not tested
C
maintenance

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/kg912/shell-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server