Shell 0

An MCP server that gives a model direct, unsandboxed access to the local machine: files, a Python runtime, a Node.js runtime, and a shell. Four tools, full system access, no guardrails.

This is deliberately not sandboxed. Point it at a machine you control, and understand the blast radius before you wire it into an agent.

Tools

• fs - filesystem access: read, write, edit, copy, move, mkdir, rmdir, list, tree, search, grep, stat, diff, hash, head, tail, and duplicate detection. 50 MB read cap, no file-watcher race conditions.
• python_exec - run Python with the full standard library and whatever is installed in the server's environment. Module-level state persists across calls.
• js_exec - run JavaScript in a real Node.js process. A state object persists across calls. Requires Node.js on PATH.
• terminal - run shell commands (cmd.exe on Windows, bash elsewhere), with optional background jobs you can poll and kill.

Forensic audit (on by default)

Every filesystem change and every code or command execution is written to a rolling on-disk audit log, so nothing the tools do is silently lost:

• Writes, edits, and deletes are snapshotted with their previous contents before the change, so any overwrite or delete is recoverable.
• Reads and searches are timestamped in an access log.
• Python and shell executions are saved with their source, status, and output.

Logs live under ./data/ next to the server, split into per-session folders, and self-prune at 50 MB (oldest first). This is accountability, not sandboxing. The tools still do whatever you ask; you just get a full paper trail of it.

Move it with FS_AUDIT_ROOT / EXEC_AUDIT_ROOT, or turn it off entirely with SHELL0_AUDIT_DISABLE=1.

Install

Requires Python 3.10 or newer (tested on 3.12).

Install as a package to get a shell-0 command on your PATH (recommended - an isolated installer keeps it off your system Python):

pipx install git+https://github.com/cutlerbenjamin1-cmd/shell-0
# or run it ad-hoc without a checkout:
uvx --from git+https://github.com/cutlerbenjamin1-cmd/shell-0 shell-0

From a local checkout: pip install .

Or skip packaging entirely, install the one dependency, and run server.py directly:

pip install -r requirements.txt

For js_exec, install Node.js from https://nodejs.org and make sure node is on your PATH. python_exec(extended_imports=true) can pre-import numpy/pandas if you add the extra: pip install "shell-0[extended]".

Use it with an MCP client

shell-0 speaks MCP over stdio. If you installed the package, point your client at the shell-0 command:

{
  "mcpServers": {
    "shell-0": {
      "command": "shell-0"
    }
  }
}

If you did not install it as a package, point python at server.py with an absolute path instead:

{
  "mcpServers": {
    "shell-0": {
      "command": "python",
      "args": ["/absolute/path/to/shell-0/server.py"]
    }
  }
}

On Windows, if the command is not found, use the full path to the installed shell-0.exe (in your pipx/venv Scripts directory) or to python.exe, with forward slashes or escaped backslashes. There is a ready-to-edit copy in example_config.json.

Running over HTTP (optional)

shell-0 speaks stdio. If your MCP client wants HTTP instead (llama.cpp's web UI, OpenWebUI, and similar), there is a companion bridge that serves shell-0 over MCP streamable HTTP: mcp-http-bridge. Run it from this directory and point your client at http://127.0.0.1:8818/mcp.

WARNING: do not expose shell-0's tools over the network without thinking hard first.

shell-0's tools (terminal, python_exec, js_exec, fs) run unsandboxed with your full privileges. Serving them over HTTP on anything other than 127.0.0.1 hands remote code execution to anyone who can reach the port - and even on 127.0.0.1, a web page in any browser tab can reach a loopback port, which is why the bridge validates the Origin header. The bridge ships a filter that disables every execution tool and fs by default (arbitrary file write is RCE-equivalent), rejects unknown browser origins, and supports a shared-secret header. Leave those defaults unless you have put real authentication and TLS in front of it, and even then only enable what you actually need.

Configuration

All optional, set as environment variables:

• SHELL0_AUDIT_DISABLE - set to 1 to turn the audit off (default: on).
• FS_AUDIT_ROOT / EXEC_AUDIT_ROOT - move the audit logs somewhere other than ./data.
• FS_AUDIT_MAX_MB / EXEC_AUDIT_MAX_MB - audit size cap before pruning (default: 50).
• OUTPUT_MAX_CHARS - hard cap on a single tool result before it gets truncated (default: 15000).
• PYTHON_EXEC_TIMEOUT - python_exec timeout in seconds (default: 30).
• MCP_DEBUG - set to true for stderr debug logging.

A word on safety

These tools run with your privileges and no sandbox. terminal and python_exec can do anything you can do from a shell. That is the whole point, but it means you should only connect shell-0 to agents and inputs you trust, on a machine where that access is acceptable. The audit log helps you see what happened after the fact. It does not stop anything from happening.

License

MIT. See LICENSE.

Testing

shell-0 has a pytest suite (coverage + regression + a live-stdio smoke layer) and an interactive driver. Full details, including the regression provenance table, are in tests/README.md.

pip install -e ".[test]"     # test deps, into a venv

pytest                       # full sweep
pytest -m regression         # only the guards for bugs actually hit
python manual.py             # drive the real server by hand over stdio

The suite is hermetic: every test runs in a temp dir with the forensic audit redirected, and never touches paths outside it. The js_exec tests skip automatically when Node.js isn't on PATH.