Skip to main content
Glama
mcp-shell

mcp-shell

by lnussbaum

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.

Related MCP server: devbox-mcp

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

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:

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:

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:

────────────────────────────────────────────────────────────────────────
⚠ 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:

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):

{
  "$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 /.

  • 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

.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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients to run shell commands on the host and retrieve exit code, stdout, and stderr, with hardened authentication and an encrypted audit log.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients to execute shell commands, manage long-running processes, and read/write files on the host machine with the permissions of the user running the server.
      5 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables remote MCP clients to access local MCP servers and command-line tools over the web, with user approval required for every connection.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Lets an MCP client read output from and write commands to a single Termius terminal you explicitly share, with per-write and per-read approval inside the app.
      2
      MIT