tumf/mcp-shell-server

A trusted execution server implementing the Model Context Protocol (MCP). It runs allowlisted commands as argv arrays, with stdin input, contained redirection, a minimal child environment, execution limits, and structured audit logging.
**This package is not a sandbox.** Allowing a command delegates that program the server process's existing OS authority. Read Trusted execution contract before configuring it.
Features
* **Argv-based Command Execution**: Allowed commands run via subprocess argv without shell-string interpretation
* **Standard Input Support**: Pass input to commands via stdin
* **Comprehensive Output**: Returns stdout, stderr, exit status, and execution time
* **Safe Pipeline Support**: Pipelines preserve and validate argv segments instead of invoking a shell
* **Execution Limits**: Server-side default timeout, maximum timeout, and output byte caps are enforced
* **Contained Redirection**: , and >> targets must stay inside the requested working directory
* **Minimal Child Environment**: Child processes receive a small allowlisted environment instead of inheriting all server secrets
* **Structured Audit Logging**: Success, rejection, timeout, output-cap, and process-error outcomes are logged with redaction
Trusted execution contract
Read this before the configuration examples below. The server emits the same warning once at startup through its logger (stderr); MCP stdout framing is unchanged.
What the server controls
mcp-shell-server enforces a boundary around its *own* behavior:
* which executable names it launches directly (ALLOW_COMMANDS, ALLOW_PATTERNS),
* argv-based process creation without shell-string interpretation,
* server-managed , and >> redirection contained under the requested working directory,
* the child environment it builds,
* timeout and output-byte limits,
* structured audit records.
What the server does not control
Allowing a command is authority delegation: the allowed program runs with the server process's existing OS identity, filesystem access, network access, and credentials. ALLOW_COMMANDS and ALLOW_PATTERNS restrict only the command names the server launches directly. They do **not** guarantee containment of:
* child processes an allowed program spawns,
* program-specific interpreters, expression languages, or plugins,
* configuration files, dotfiles, or environment-driven behavior the program reads on its own,
* filesystem reads and writes the program performs itself, outside server-managed redirection,
* network access the program performs itself.
The command-specific rejection rules described under Security are best-effort defense in depth against known dangerous argument forms. They are non-exhaustive, and they are not a proof that an allowed program is safe.
Untrusted input requires external isolation
A trusted, authenticated MCP client does not make the *content* it processes trusted. Model-provided text, fetched web pages, issue text, and repository contents are untrusted input even when the client itself is trusted, and an LLM can be induced to construct a request from that content.
If any request or any file the server can reach may derive from untrusted input, run the server inside an independently enforced OS boundary (container, VM, jail, or OS policy) that provides:
* **Least-privilege identity** — a dedicated non-root user with no administrative rights on the host.
* **Filesystem scope** — only the directories the workload needs, mounted read-only where possible, with host configuration, SSH keys, and cloud credential files out of reach.
* **Network restrictions** — egress denied by default, allowing only the destinations the workload requires.
* **Credential exclusion** — no ambient tokens, cloud instance-metadata access, or agent sockets reachable from the server process.
* **Descendant-process containment** — a process/cgroup namespace so processes spawned by an allowed program are bounded and reaped with the sandbox.
* **Resource limits** — CPU, memory, disk, process-count, and wall-clock caps enforced outside this package.