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, touch, head, tail, and duplicate detection. 50 MB read cap (FS_MAX_READ_BYTES), no file-watcher race conditions. Content is written as sent: an existing file keeps its line endings and encoding (UTF-8, UTF-8 BOM, UTF-16, Latin-1), and new files get exactly what was sent, except .bat/.cmd, which use CRLF. Only .py and .json get repairs (code fences, smart-quote delimiters), only when the content doesn't parse, and a repair is kept only if it makes the content parse. A Python write that still won't parse is rejected; other file types are never rewritten. edit replaces exact text with no re-indenting and fails if old_text matches more than once, unless replace_all is set.

• python_exec - run Python with the full standard library and whatever is installed in the server's environment. Code runs in a persistent worker subprocess, so module-level state survives across calls and a timeout is a real SIGKILL of the worker, not a best-effort nudge - the next call just gets a fresh one. Broken code gets fence and quote repairs, kept only if the result parses.

• js_exec - run JavaScript in a real Node.js process. A state object persists across calls, loaded from and saved to a JSON file on disk; concurrent calls are serialized so they can't race that file. Requires Node.js on PATH.

• terminal - run shell commands (cmd.exe on Windows, bash elsewhere), with optional background jobs you can poll and kill. A timeout kills the whole process tree it spawned, not just the top-level command. cmd.exe refuses multi-line commands, because it would silently run only the first line. On Windows, shell='wsl' runs the command as a bash script in WSL with no cmd quoting in between, so %, quotes and multi-line scripts are safe, and its timeouts and kills stop only that command's own processes. Output decodes correctly from UTF-8, the Windows OEM code page, or UTF-16, and keeps its indentation.

Related MCP server: maic-server-fs-mcp

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:

• Every write mode (overwrite, append, insert, replace_lines), edit, copy, move, and delete is snapshotted with its previous contents before the change - including whatever an overwriting copy/move is about to clobber at the destination - so any of them is recoverable.

• Reads, greps, filename searches, and touches are timestamped in an access log.

• Python, JavaScript, 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, checked on every write - not just at startup). This is accountability, not sandboxing. The tools still do whatever you ask; you just get a full paper trail of it. The one exception: rmdir refuses to delete drive roots, UNC roots, or your home directory outright, with no override - the only hardcoded guardrail in an otherwise unrestricted tool.

Move it with FS_AUDIT_ROOT / EXEC_AUDIT_ROOT, or turn it off entirely with SHELL0_AUDIT_DISABLE=1. Each tool module (tools/filesystem.py, tools/python_runner.py, tools/js_runner.py, tools/terminal_exec.py) carries its own copy of this audit logic rather than importing a shared one - deliberately, so any single tool file can be lifted out and dropped into another project with nothing else to bring along.

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

• FS_MAX_READ_BYTES - full-file read cap in bytes for fs(action="read") with no limit (default: 50MB). Chunked reads (offset/limit) stream instead of loading the whole file, so they aren't subject to this cap.

• FS_MAX_TREE_DEPTH - max directory depth for tree, search, and grep (default: 15).

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

• PYTHON_EXEC_MAX_MEMORY - python_exec worker address-space cap in bytes (default: 8GB). POSIX only (RLIMIT_AS); no-op on Windows, which has no equivalent cheap hard cap.

• PYTHON_EXEC_MAX_OUTPUT - max captured stdout/stderr chars per python_exec call before clipping (default: 1,000,000).

• JS_EXEC_TIMEOUT - js_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.