Skip to main content
Glama
cutlerbenjamin1-cmd

shell-0

by cutlerbenjamin1-cmd
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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. Writes get repair-only-if-broken autofixing: markdown code fences and smart quotes are stripped/normalized, and a JSON or Python write that wouldn't parse is rejected instead of silently corrupting the file.

  • 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. Same fence/quote autofixing as fs.

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

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.

Available Tools

4 tools
fsA

Full shell filesystem access (UNSANDBOXED, 50MB read limit). Use for all file operations. Doesn't encounter race conditions with file watchers. grep contains all the functionality of bash + powershell filesystem search. Auto-fixes code fences and smart quotes on write. Actions: read, write, edit, delete, copy, move, mkdir, rmdir, list, tree, search, grep, stat, diff, hash, touch, head, tail, duplicates. edit: [{old_text, new_text}]. grep: regex search in directories. diff: compare files/strings. hash: SHA256/MD5 checksums. duplicates: find duplicate files by hash.

ParametersJSON Schema
NameRequiredDescriptionDefault
modeNoWrite mode (default: overwrite)
pathNo
editsNoFor edit: [{old_text, new_text}, ...]
limitNoLines to read (0=all) or lines to replace in replace_lines mode
linesNoFor head/tail: number of lines (default: 10)
regexNoFor grep: treat pattern as regex instead of substring (default: false)
actionYes
offsetNoStarting line (1-based) for read chunk or write insert/replace
path_aNoFor diff: first file path
path_bNoFor diff: second file path
confirmNoFor rmdir: confirm deleting a directory that contains more than 50 items.
contentNo
dry_runNoFor edit: preview diff without writing
patternNo
min_sizeNoFor duplicates: min file size in bytes (default: 1)
algorithmNoFor duplicates: hash algorithm (default: sha256)
content_aNoFor diff: first content string
content_bNoFor diff: second content string
max_depthNoFor grep: max directory depth
recursiveNoFor rmdir: recurse into non-empty directories.
algorithmsNoFor hash: list of algorithms (md5, sha1, sha256, sha512)
destinationNo
ignore_caseNoFor grep: case-insensitive search (default: false)
max_resultsNoFor grep: max matches
file_patternNoFor grep: file glob (*.py)
context_linesNoFor grep/diff: lines of context (default: 0/3)
output_formatNoFor diff: output format (default: unified)
create_parentsNoFor touch: create parent dirs (default: true)
max_line_lengthNoFor grep: max chars per line in output (default: 500)
include_metadataNoFor list: include size, type, and mtime for each entry.
preserve_indentationNoFor edit: apply old_text's leading indentation to new_text (default: true).

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses important behavioral traits: 'UNSANDBOXED, 50MB read limit' and 'Auto-fixes code fences and smart quotes on write.' However, with 31 parameters and many actions, it lacks detail on side effects or specific behaviors for each action. Given no annotations, the description carries the burden but provides moderate transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but front-loaded with critical info (unsandboxed, read limit). It then lists all actions without clear structure or grouping. While efficient, it could be better organized for readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the full range of 19 actions, important constraints (read limit, no race conditions), and additional features (auto-fix). With no output schema, it provides sufficient context for the tool's capabilities, though more detail on return values for each action would enhance completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With schema description coverage at 84%, the schema already documents most parameters. The description adds minimal value, e.g., listing actions and mentioning 'edit: [{old_text, new_text}]' but does not enhance understanding beyond the schema. It misses opportunities to clarify parameter usage or dependencies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Full shell filesystem access (UNSANDBOXED, 50MB read limit). Use for all file operations.' The tool's purpose is specific and distinct from sibling tools js_exec, python_exec, and terminal, which are code execution environments.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description advises 'Use for all file operations' and notes that it 'Doesn't encounter race conditions with file watchers.' It also mentions that 'grep contains all the functionality of bash + powershell filesystem search.' This provides good context for when to use this tool, although it does not explicitly exclude scenarios or mention alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

js_execA

Execute JavaScript code in a full Node.js environment. Returns an object with keys: success (bool), output (combined stdout/stderr), stdout, stderr, exitCode, and outputTruncated (bool if output exceeded 100KB). Use this tool when: (1) manipulating JSON data where JavaScript's native handling is cleaner than Python, (2) testing algorithms where JS syntax is preferred, (3) using npm packages not available in Python, (4) working with Node.js-specific APIs. Do NOT use this tool when: (1) generating visualizations - Node.js has no DOM, canvas, or browser APIs (use python_exec with matplotlib instead), (2) the task is equally achievable in Python (prefer python_exec for consistency). The tool provides persistent state across calls via a state object that is automatically loaded from and saved to .shell0_js_state.json in the working directory. Assign values to state.myKey to persist them between invocations. Limitations: 30-second default timeout (configurable up to 600s), 100K character source limit, 2000 line limit, 100KB output cap. On timeout the process is killed. Syntax errors return in stderr with line numbers. Requires Node.js on PATH.

ParametersJSON Schema
NameRequiredDescriptionDefault
codeYesJavaScript source code to execute. Supports require(), async/await, and ES6+ syntax. Use console.log() for output. Access persistent state via the `state` object (auto-loaded/saved). Example: `const data = require('fs').readFileSync('file.json'); console.log(JSON.parse(data));`
timeoutNoExecution timeout in seconds. Default: 30. Maximum: 600.

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses behavior: return object structure, persistent state mechanism, timeouts, source/line limits, output cap, error handling, and requirement for Node.js on PATH. This is comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with clear sections (purpose, output, usage, state, limitations), but slightly verbose. Could tighten some examples, but overall effective.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and two parameters, the description covers all critical aspects: purpose, usage, output, state handling, and limitations, leaving no significant gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds value by explaining state persistence and providing an example for the 'code' parameter, going beyond what the schema descriptions offer.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that it 'Execute JavaScript code in a full Node.js environment' and provides four specific use cases (JSON manipulation, algorithms, npm packages, Node.js APIs) that distinguish it from siblings like python_exec and fs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells when to use (four bullet points) and when NOT to use (two bullet points, e.g., visualizations and Python-preferred tasks), giving clear guidance on tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

python_execA

Execute Python code with full system access. Returns {success, output, result, error}. Use for: data processing, file operations, API calls, system automation, any Python task. Prefer over js_exec unless JS-specific features needed. UNLOCKED: all imports (os, subprocess, requests, pathlib), file I/O, network access. Persistent state via module-level variables across calls. Limits: 30s timeout (PYTHON_EXEC_TIMEOUT env), 100k chars, 2k lines, 20k AST nodes.

ParametersJSON Schema
NameRequiredDescriptionDefault
codeYesPython source code. Use print() for output. Last expression value returned in 'result'.
extended_importsNoPre-import numpy/pandas if available. Default: false.

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully covers behavior: full system access, allowed imports, persistent state, limits (timeout, chars, lines, AST nodes). It discloses permissions and constraints comprehensively.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with no wasted words. It is front-loaded with purpose, then usage, then details, using bullet points for readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema or annotations, the description is complete: it covers purpose, usage, behavioral traits, parameter details, limits, and expected output format. It leaves no significant gaps for a code execution tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds valuable semantics for the 'code' parameter (use print() for output, last expression returned in 'result'), going beyond the schema. 'extended_imports' is adequately described.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Execute Python code with full system access,' specifying the verb and resource. It lists example use cases (data processing, file operations, etc.) and distinguishes from js_exec, making the purpose highly specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Use for: data processing... any Python task' and 'Prefer over js_exec unless JS-specific features needed,' providing clear guidance on when to use this tool versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

terminalA

Execute shell commands. Returns {success, output, exit_code, duration_seconds}. Use for: git, npm, pip, system commands, anything requiring shell. UNRESTRICTED - full privileges, no sandboxing. Windows: cmd.exe, Unix: bash. Timeout: 120s default, 600s max. Background: run_in_background=true returns task_id. Use bg_status/bg_kill/bg_list to manage. For file ops prefer fs; for Python prefer python_exec.

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdNoWorking directory. Default: current dir.
bg_killNoKill a running background task by task_id.
bg_listNoList all background tasks with status. Set true.
commandNoShell command to execute. Supports pipes, redirects, chaining (&&, ||).
timeoutNoTimeout in seconds. Default: 120. Max: 600.
bg_statusNoGet status/output of a background task by task_id.
descriptionNoBrief description for logging (e.g., 'Install deps').
run_in_backgroundNoRun command in background, return task_id immediately. Default: false.

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses return format, unrestricted privileges, no sandboxing, shell differences (Windows cmd.exe, Unix bash), timeouts (120s default, 600s max), and background task management. Could add explicit warning about destructive potential, but overall strong.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise yet comprehensive; each sentence adds unique information. Front-loaded with core purpose, then progressively details. No redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 8 parameters, no output schema, and no annotations, the description covers purpose, usage, behavior, return format, timeouts, background tasks, cross-platform, and alternatives. Highly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (baseline 3). Description adds value by grouping background-related params (bg_status, bg_kill, bg_list) and clarifying timeout defaults and max, beyond schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Execute shell commands' and enumerates specific use cases (git, npm, pip). It distinguishes from siblings by advising 'For file ops prefer fs; for Python prefer python_exec.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly lists when to use ('Use for: git, npm, pip, system commands, anything requiring shell') and provides exclusions ('For file ops prefer fs; for Python prefer python_exec'). Also warns of unrestricted nature.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 4 tool updatesv0.1.0
    • First observedfs
    • First observedjs_exec
    • First observedpython_exec
    • First observedterminal
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0
Disambiguation3/5

Tools are generally distinct but have overlapping capabilities: terminal can run scripts that js_exec and python_exec handle, and fs operations can be done via terminal as well. Descriptions provide guidance, but an agent might still be uncertain about which tool to use for mixed tasks.

Naming Consistency3/5

Naming is inconsistent: 'fs' and 'terminal' are noun-based, while 'js_exec' and 'python_exec' follow a language+verb pattern. This mix makes the set less predictable.

Tool Count4/5

4 tools is appropriate for a general-purpose shell server, covering files, two scripting languages, and raw command execution. It is slightly on the lower side but not insufficient.

Completeness4/5

The tool surface covers the core domain of shell operations: file management, code execution, and system commands. Missing features like persistent state sharing across executors or advanced process control are minor gaps.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/cutlerbenjamin1-cmd/shell-0'

If you have feedback or need assistance with the MCP directory API, please join our Discord server