Back to search
mcp-shell
MCP serverGitHub
A minimal MCP server that runs commands in the user's environment (on the host, outside any sandbox)
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/lnussbaum--mcp-shell)HTML
<a href="/listings/lnussbaum--mcp-shell"><img src="/api/listings/lnussbaum--mcp-shell/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
python3 -m venv .venv .venv/bin/pip install -r requirements.txt .venv/bin/python test_mcp_shell.py # 16 checks, ~10s, all must pass
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 210 lines · 1 finding marked
- # mcp-shell
- A minimal MCP server that runs commands **in the user's environment** (on the
- host, outside any sandbox). Every command must be approved by **the human at
- the server's terminal** — the one channel a compromised MCP client cannot
- touch.
- > **Why a daemon, not a stdio server.** A stdio MCP server is a *child
- > process* of the client: it inherits the client's environment, privileges,
- > and **sandbox** — and it gets no controlling terminal, so terminal
- > confirmation could never be shown. mcp-shell is therefore an HTTP daemon
- > only: you run it yourself, outside the sandbox, and point OpenCode at it
- > as a *remote* MCP server. Commands execute with the daemon's authority,
- > and every confirmation appears on the terminal you launched it from.
- ## Confirmation: one mode, the terminal
- Every `run_command` call prompts on the server's controlling terminal
- (`/dev/tty`) and blocks until you answer. An explicit `y` runs the command;
- anything else — `n`, Enter, EOF, a missing terminal — refuses it
- (fail-closed). The prompt and your answer never pass through the MCP client,
- so a compromised client cannot approve on your behalf, and cannot forge,
- hide, or auto-answer the confirmation.
- There is one confirmation channel by design: the terminal. Alternatives
- were ruled out on security and reliability grounds — an in-client form
- (elicitation) depends on the client to display it faithfully and can hang
- the call when it doesn't, and client-side permission rules are only as
- trustworthy as the client itself. The terminal is out-of-band: it works
- regardless of who the client is.
- > When a call appears to hang in OpenCode, it is waiting for you at the
- > daemon's terminal. The tool's description tells the model this too.
- ## Per-session authorization (default on)
- Confirming every single command is the WHAT gate. Session authorization adds
- a WHO gate: the **first `tools/call` of each MCP session** triggers one
- terminal prompt — `session <id>, first request <cmd>… Authorize?` Approving
- authorizes that session for the daemon's lifetime; refusing it means every
- command from that session is refused. The authorization is dropped when the
- client disconnects (session DELETE). Disable with `MCP_SHELL_SESSION_AUTH=0`.
- ## Quick start
- ```sh
- python3 -m venv .venv
- .venv/bin/pip install -r requirements.txt
- .venv/bin/python test_mcp_shell.py # 16 checks, ~10s, all must pass
- ```
- ## Daemon usage (the sandbox-evasion setup)
- Start the daemon **outside the sandbox**, in your own terminal:
- ```sh
- cd /path/to/mcp-shell
- MCP_SHELL_DEBUG=1 .venv/bin/python mcp_shell.py
- ```
- (The `daemon` argument is optional — the daemon is the only mode.)
- It prints its endpoint and auth setup once:
- ```text
- mcp-shell daemon listening on http://127.0.0.1:7801/mcp
- auth: session auth at this terminal
- confirmation: every command prompts at this terminal
- debug off (MCP_SHELL_DEBUG=1 to enable)
- Set MCP_SHELL_SESSION_AUTH=0 to disable session auth; MCP_SHELL_PORT for the port.
- ```
- HTTP logging (access lines, session chatter) stays quiet by default so the
- approval prompts are readable; `MCP_SHELL_DEBUG=1` enables both the debug
- lines and the HTTP logs. A prompt looks like this on your terminal:
- ```text
- ────────────────────────────────────────────────────────────────────────
- ⚠ mcp-shell — command approval requested
- $ git status
- Approve? [y/N]
- ```
- with the command bolded, long commands wrapped (never truncated), and an
- immediate `✓ approved — running` / `✗ refused` verdict after your keystroke,
- plus a dim `↳ finished: exit 0` line when the command completes. Colors are
- used when the terminal supports them and disabled with `NO_COLOR` or
- `TERM=dumb`.
- Register it in OpenCode as a **remote** server. With the CLI:
- ```sh
- opencode mcp add mcp-shell --url http://127.0.0.1:7801/mcp
- ```
- Or by hand in `opencode.jsonc` (global: `~/.config/opencode/opencode.jsonc`);
- **disabled by default** so OpenCode only connects when you explicitly opt in
- (flip to `false`, remove the field, or toggle interactively with `/mcps`):
- ```jsonc
- {
- "$schema": "https://opencode.ai/config.json",
- "mcp": {
- "servers": {
- "mcp-shell": {
- "type": "remote",
- "url": "http://127.0.0.1:7801/mcp",
- "oauth": false,
- "disabled": true
- }
- }
- }
- }
- ```
- Check with `opencode mcp list` (should show `connected` once enabled). When
- the model calls `run_command`: the first call per session prompts
- `Authorize this session?` at the daemon terminal; every call then prompts
- `Approve?` with the exact command. Answer `y` at the terminal to proceed.
- ## Tool: `run_command`
- | Parameter | Type | Description |
- |-----------|------|-------------|
- | `argv` | `list[str]` | Command as an argv array, e.g. `["git", "status"]`. No shell involved. |
- | `cwd` | `str?` | Optional working directory (absolute path). Defaults to the server's cwd. |
- Returns `command` (shell-quoted display), `exit_code`, `stdout`, `stderr`,
- `timed_out`, `truncated`.
- ## Security model
- - **Terminal confirmation, fail-closed.** The command runs only on an
- explicit `y` at the server's terminal. Every other outcome — decline,
- EOF, missing `/dev/tty`, client disconnect — refuses.
- - **Out-of-band by construction.** Prompt and answer live on the terminal,
- not in MCP. A compromised client sees the call but cannot approve it,
- hide the prompt, or answer it.
- - **Session authorization.** Each session must be
- authorized once at the terminal before any of its commands even reach
- per-command confirmation. WHO and WHAT are separate gates.
- - **No shell by construction.** Commands are argv arrays; no string
- interpolation, so `;`, `&&`, backticks, and `$()` are literal text.
- Test: `["echo", "a;rm -rf /"]` prints `a;rm -rf /`.
- Warning: Runs `rm -rf` against a root or home-directory path
- Line 146 on GitHub
- - **No executable deny list.** Every command is judged solely at the
- terminal, so the prompt is the full picture of what will run.
- - **Timeout with process-group kill.** Over-timeout commands are SIGKILLed
- as a group (`start_new_session=True`), so children cannot outlive the
- call. `exit_code` is `-9`, `timed_out` is `true`.
- - **Output cap.** Each of stdout and stderr is capped (default 1 MiB per
- stream) with head+tail truncation, so long runs don't blow up model
- context.
- - **Your environment by default.** Commands inherit the server's full
- environment — your user account's exports, since you start the server from
- your shell. Server-internal `MCP_SHELL_*` configuration is always stripped
- so it never leaks into commands. Set
- `MCP_SHELL_ENV=NAME,NAME,...` to restrict commands to an allowlist
- instead.
- - **Loopback + rebinding protection.** The daemon binds to `127.0.0.1`
- only and validates Host/Origin against DNS-rebinding attacks.
- - **Debug logging.** `MCP_SHELL_DEBUG=1` prints each decision (calls
- received, session prompts and outcomes, approvals, executions) and
- enables HTTP access logs; by default both stay quiet so prompts are
- readable — enough to diagnose any "nothing happened".
- ## Configuration
- | Variable | Default | Description |
- |----------|---------|-------------|
- | `MCP_SHELL_SESSION_AUTH` | on | Require one terminal authorization per MCP session. `0` disables it. |
- | `MCP_SHELL_PORT` | `7801` | Daemon HTTP port. |
- | `MCP_SHELL_TIMEOUT` | `120` | Seconds before a command is killed (group SIGKILL). |
- | `MCP_SHELL_OUTPUT_CAP` | `1048576` | Max bytes per stream (stdout / stderr separately) before truncation. |
- | `MCP_SHELL_ENV` | unset (full inheritance) | Comma-separated env var names: restrict commands to this allowlist. Unset = inherit your full environment (with `MCP_SHELL_*` stripped). |
- | `MCP_SHELL_DEBUG` | `0` | `1` enables per-decision debug lines **and** HTTP logs; default keeps the terminal quiet for prompts. |
- ## Tests
- `test_mcp_shell.py` (16 checks, ~10s) drives the daemon over real
- streamable-HTTP MCP connections against a real PTY (via `login_tty`, so the
- daemon genuinely owns a controlling terminal):
- - usage error for an unknown run mode
- - daemon: session authorize/approve, fresh-session re-authorization,
- command refusal, session refusal, credential-less HTTP reachability,
- no-tty fail-closed (session auth on and off), no-shell literal
- metacharacters, missing executable, bad cwd, cwd, environment inheritance
- + `MCP_SHELL_*` stripping, `MCP_SHELL_ENV` restriction, timeout kill
- ```sh
- .venv/bin/python test_mcp_shell.py
- ```
- ## Notes
- - Official Python SDK (`mcp` 2.x): the high-level server class is
- `MCPServer`. This server uses no elicitation — the terminal is the only
- confirmation channel.
- - POSIX only: `/dev/tty`, `os.login_tty`, `TIOCGWINSZ`, and process-group
- signals are Unix APIs; there is no Windows or macOS support and the test
- suite runs on Linux.
- - For manual debugging of any MCP server, use the official
- **MCP Inspector**: `npx @modelcontextprotocol/inspector`.
- - OpenCode's normalized tool name is `mcp-shell_run_command` for permission
- rules; `codemode: false` on the server entry exposes the tool directly.
- - Running host commands is inherently risky; this server exists to make
- that *auditable and gated*, not safe. Read every prompt carefully —
- especially what a compromised client could do with your `y`.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.