Skip to content
Back to search

mcp-shell

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lnussbaum--mcp-shell/badge.svg)](/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
  1. # mcp-shell
  2. A minimal MCP server that runs commands **in the user's environment** (on the
  3. host, outside any sandbox). Every command must be approved by **the human at
  4. the server's terminal** — the one channel a compromised MCP client cannot
  5. touch.
  6. > **Why a daemon, not a stdio server.** A stdio MCP server is a *child
  7. > process* of the client: it inherits the client's environment, privileges,
  8. > and **sandbox** — and it gets no controlling terminal, so terminal
  9. > confirmation could never be shown. mcp-shell is therefore an HTTP daemon
  10. > only: you run it yourself, outside the sandbox, and point OpenCode at it
  11. > as a *remote* MCP server. Commands execute with the daemon's authority,
  12. > and every confirmation appears on the terminal you launched it from.
  13. ## Confirmation: one mode, the terminal
  14. Every `run_command` call prompts on the server's controlling terminal
  15. (`/dev/tty`) and blocks until you answer. An explicit `y` runs the command;
  16. anything else — `n`, Enter, EOF, a missing terminal — refuses it
  17. (fail-closed). The prompt and your answer never pass through the MCP client,
  18. so a compromised client cannot approve on your behalf, and cannot forge,
  19. hide, or auto-answer the confirmation.
  20. There is one confirmation channel by design: the terminal. Alternatives
  21. were ruled out on security and reliability grounds — an in-client form
  22. (elicitation) depends on the client to display it faithfully and can hang
  23. the call when it doesn't, and client-side permission rules are only as
  24. trustworthy as the client itself. The terminal is out-of-band: it works
  25. regardless of who the client is.
  26. > When a call appears to hang in OpenCode, it is waiting for you at the
  27. > daemon's terminal. The tool's description tells the model this too.
  28. ## Per-session authorization (default on)
  29. Confirming every single command is the WHAT gate. Session authorization adds
  30. a WHO gate: the **first `tools/call` of each MCP session** triggers one
  31. terminal prompt — `session <id>, first request <cmd>… Authorize?` Approving
  32. authorizes that session for the daemon's lifetime; refusing it means every
  33. command from that session is refused. The authorization is dropped when the
  34. client disconnects (session DELETE). Disable with `MCP_SHELL_SESSION_AUTH=0`.
  35. ## Quick start
  36. ```sh
  37. python3 -m venv .venv
  38. .venv/bin/pip install -r requirements.txt
  39. .venv/bin/python test_mcp_shell.py # 16 checks, ~10s, all must pass
  40. ```
  41. ## Daemon usage (the sandbox-evasion setup)
  42. Start the daemon **outside the sandbox**, in your own terminal:
  43. ```sh
  44. cd /path/to/mcp-shell
  45. MCP_SHELL_DEBUG=1 .venv/bin/python mcp_shell.py
  46. ```
  47. (The `daemon` argument is optional — the daemon is the only mode.)
  48. It prints its endpoint and auth setup once:
  49. ```text
  50. mcp-shell daemon listening on http://127.0.0.1:7801/mcp
  51. auth: session auth at this terminal
  52. confirmation: every command prompts at this terminal
  53. debug off (MCP_SHELL_DEBUG=1 to enable)
  54. Set MCP_SHELL_SESSION_AUTH=0 to disable session auth; MCP_SHELL_PORT for the port.
  55. ```
  56. HTTP logging (access lines, session chatter) stays quiet by default so the
  57. approval prompts are readable; `MCP_SHELL_DEBUG=1` enables both the debug
  58. lines and the HTTP logs. A prompt looks like this on your terminal:
  59. ```text
  60. ────────────────────────────────────────────────────────────────────────
  61. ⚠ mcp-shell — command approval requested
  62. $ git status
  63. Approve? [y/N]
  64. ```
  65. with the command bolded, long commands wrapped (never truncated), and an
  66. immediate `✓ approved — running` / `✗ refused` verdict after your keystroke,
  67. plus a dim `↳ finished: exit 0` line when the command completes. Colors are
  68. used when the terminal supports them and disabled with `NO_COLOR` or
  69. `TERM=dumb`.
  70. Register it in OpenCode as a **remote** server. With the CLI:
  71. ```sh
  72. opencode mcp add mcp-shell --url http://127.0.0.1:7801/mcp
  73. ```
  74. Or by hand in `opencode.jsonc` (global: `~/.config/opencode/opencode.jsonc`);
  75. **disabled by default** so OpenCode only connects when you explicitly opt in
  76. (flip to `false`, remove the field, or toggle interactively with `/mcps`):
  77. ```jsonc
  78. {
  79. "$schema": "https://opencode.ai/config.json",
  80. "mcp": {
  81. "servers": {
  82. "mcp-shell": {
  83. "type": "remote",
  84. "url": "http://127.0.0.1:7801/mcp",
  85. "oauth": false,
  86. "disabled": true
  87. }
  88. }
  89. }
  90. }
  91. ```
  92. Check with `opencode mcp list` (should show `connected` once enabled). When
  93. the model calls `run_command`: the first call per session prompts
  94. `Authorize this session?` at the daemon terminal; every call then prompts
  95. `Approve?` with the exact command. Answer `y` at the terminal to proceed.
  96. ## Tool: `run_command`
  97. | Parameter | Type | Description |
  98. |-----------|------|-------------|
  99. | `argv` | `list[str]` | Command as an argv array, e.g. `["git", "status"]`. No shell involved. |
  100. | `cwd` | `str?` | Optional working directory (absolute path). Defaults to the server's cwd. |
  101. Returns `command` (shell-quoted display), `exit_code`, `stdout`, `stderr`,
  102. `timed_out`, `truncated`.
  103. ## Security model
  104. - **Terminal confirmation, fail-closed.** The command runs only on an
  105. explicit `y` at the server's terminal. Every other outcome — decline,
  106. EOF, missing `/dev/tty`, client disconnect — refuses.
  107. - **Out-of-band by construction.** Prompt and answer live on the terminal,
  108. not in MCP. A compromised client sees the call but cannot approve it,
  109. hide the prompt, or answer it.
  110. - **Session authorization.** Each session must be
  111. authorized once at the terminal before any of its commands even reach
  112. per-command confirmation. WHO and WHAT are separate gates.
  113. - **No shell by construction.** Commands are argv arrays; no string
  114. interpolation, so `;`, `&&`, backticks, and `$()` are literal text.
  115. Test: `["echo", "a;rm -rf /"]` prints `a;rm -rf /`.
  116. - **No executable deny list.** Every command is judged solely at the
  117. terminal, so the prompt is the full picture of what will run.
  118. - **Timeout with process-group kill.** Over-timeout commands are SIGKILLed
  119. as a group (`start_new_session=True`), so children cannot outlive the
  120. call. `exit_code` is `-9`, `timed_out` is `true`.
  121. - **Output cap.** Each of stdout and stderr is capped (default 1 MiB per
  122. stream) with head+tail truncation, so long runs don't blow up model
  123. context.
  124. - **Your environment by default.** Commands inherit the server's full
  125. environment — your user account's exports, since you start the server from
  126. your shell. Server-internal `MCP_SHELL_*` configuration is always stripped
  127. so it never leaks into commands. Set
  128. `MCP_SHELL_ENV=NAME,NAME,...` to restrict commands to an allowlist
  129. instead.
  130. - **Loopback + rebinding protection.** The daemon binds to `127.0.0.1`
  131. only and validates Host/Origin against DNS-rebinding attacks.
  132. - **Debug logging.** `MCP_SHELL_DEBUG=1` prints each decision (calls
  133. received, session prompts and outcomes, approvals, executions) and
  134. enables HTTP access logs; by default both stay quiet so prompts are
  135. readable — enough to diagnose any "nothing happened".
  136. ## Configuration
  137. | Variable | Default | Description |
  138. |----------|---------|-------------|
  139. | `MCP_SHELL_SESSION_AUTH` | on | Require one terminal authorization per MCP session. `0` disables it. |
  140. | `MCP_SHELL_PORT` | `7801` | Daemon HTTP port. |
  141. | `MCP_SHELL_TIMEOUT` | `120` | Seconds before a command is killed (group SIGKILL). |
  142. | `MCP_SHELL_OUTPUT_CAP` | `1048576` | Max bytes per stream (stdout / stderr separately) before truncation. |
  143. | `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). |
  144. | `MCP_SHELL_DEBUG` | `0` | `1` enables per-decision debug lines **and** HTTP logs; default keeps the terminal quiet for prompts. |
  145. ## Tests
  146. `test_mcp_shell.py` (16 checks, ~10s) drives the daemon over real
  147. streamable-HTTP MCP connections against a real PTY (via `login_tty`, so the
  148. daemon genuinely owns a controlling terminal):
  149. - usage error for an unknown run mode
  150. - daemon: session authorize/approve, fresh-session re-authorization,
  151. command refusal, session refusal, credential-less HTTP reachability,
  152. no-tty fail-closed (session auth on and off), no-shell literal
  153. metacharacters, missing executable, bad cwd, cwd, environment inheritance
  154. + `MCP_SHELL_*` stripping, `MCP_SHELL_ENV` restriction, timeout kill
  155. ```sh
  156. .venv/bin/python test_mcp_shell.py
  157. ```
  158. ## Notes
  159. - Official Python SDK (`mcp` 2.x): the high-level server class is
  160. `MCPServer`. This server uses no elicitation — the terminal is the only
  161. confirmation channel.
  162. - POSIX only: `/dev/tty`, `os.login_tty`, `TIOCGWINSZ`, and process-group
  163. signals are Unix APIs; there is no Windows or macOS support and the test
  164. suite runs on Linux.
  165. - For manual debugging of any MCP server, use the official
  166. **MCP Inspector**: `npx @modelcontextprotocol/inspector`.
  167. - OpenCode's normalized tool name is `mcp-shell_run_command` for permission
  168. rules; `codemode: false` on the server entry exposes the tool directly.
  169. - Running host commands is inherently risky; this server exists to make
  170. that *auditable and gated*, not safe. Read every prompt carefully —
  171. especially what a compromised client could do with your `y`.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.