mcp-shell
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 passDaemon 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/mcpOr 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 |
|
| Command as an argv array, e.g. |
|
| 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
yat 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 /"]printsa;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_codeis-9,timed_outistrue.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. SetMCP_SHELL_ENV=NAME,NAME,...to restrict commands to an allowlist instead.Loopback + rebinding protection. The daemon binds to
127.0.0.1only and validates Host/Origin against DNS-rebinding attacks.Debug logging.
MCP_SHELL_DEBUG=1prints 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 |
| on | Require one terminal authorization per MCP session. |
|
| Daemon HTTP port. |
|
| Seconds before a command is killed (group SIGKILL). |
|
| Max bytes per stream (stdout / stderr separately) before truncation. |
| unset (full inheritance) | Comma-separated env var names: restrict commands to this allowlist. Unset = inherit your full environment (with |
|
|
|
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_ENVrestriction, timeout kill
.venv/bin/python test_mcp_shell.pyNotes
Official Python SDK (
mcp2.x): the high-level server class isMCPServer. 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_commandfor permission rules;codemode: falseon 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Use a person's computer after they approve it there: files, Terminal, browser, local MCP.
Use a person's computer after they approve it there: files, Terminal, browser, local MCP.
SSH client, server management and one remote MCP URL for your machines, with human approvals.
An authenticated remote MCP server for user-owned devices and one-shot capability invocation.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to run shell commands on the host and retrieve exit code, stdout, and stderr, with hardened authentication and an encrypted audit log.-
- AlicenseNot gradedqualityCmaintenanceEnables 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 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables remote MCP clients to access local MCP servers and command-line tools over the web, with user approval required for every connection.1MIT
- AlicenseNot gradedqualityCmaintenanceLets 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.2MIT