LabscoMCP early access ↗
soniricoMCP SERVER

MCP Shell

File, search and git tools for a model, confined to one working directory — with a raw shell only if you opt in.

by sonirico ↗Editors, Terminals & Local Dev EnvironmentCommunity

LABSCO SUMMARY

Safe by default is the part other shell servers skip.

Most shell servers hand the model a command string and then try to police it. This one takes the string away: by default the server builds every command itself, so the model reads, searches and inspects git history through typed tools that cannot reach outside the working directory. Writes and scripts are switches you turn on, and a raw shell is a separate mode you have to ask for by name.

What it is

An MCP server written in Go that gives a model typed tools for files, search and git instead of a shell string. With no configuration it boots in secure mode: read-only file, grep/glob and git inspection tools, every path confined to working_directory, and no raw shell command. A YAML config turns on writes and scripts; MCP_SHELL_ALLOW_UNSAFE=1 swaps all of it for a single unrestricted shell_exec.

What you get

  • Read-only tools on by default: read_file, list_dir, glob, grep, stat, diff_files and system_info
  • Git inspection on by default — git_status, git_log, git_diff, git_show, git_blame, branches, tags, stashes and remotes — with no push, fetch or clone
  • Path confinement: every path parameter is resolved against working_directory, symlinks followed, and anything outside it is rejected
  • File and git write tools — write_file, edit_file, mkdir, move, delete, git_add, git_commit, git_switch, git_restore, git_stash — only after you set writes_enabled: true
  • run_script for scripts you define in the config: the client picks a name, the command behind it is yours and cannot be altered
  • Policy knobs in YAML: working_directory, max_execution_time, max_output_size, run_as_user and audit_log
  • An unrestricted mode, only with MCP_SHELL_ALLOW_UNSAFE=1, whose single tool shell_exec runs bash -c with no validation

Requirements

The Docker image sonirico/mcp-shell:latest — non-root, Alpine-based — or a Go build with make install. No config file is needed to start safely. MCP_SHELL_SEC_CONFIG_FILE points at your YAML policy; MCP_SHELL_ALLOW_UNSAFE=true disables all validation. Logging is controlled by MCP_SHELL_LOG_LEVEL, MCP_SHELL_LOG_FORMAT and MCP_SHELL_LOG_OUTPUT. The README recommends pairing the container with an OS sandbox — read-only filesystem, dropped capabilities — as defense in depth.

Setup effort

One command — docker run -it --rm -v /tmp/mcp-workspace:/tmp/mcp-workspace sonirico/mcp-shell:latest

See installation options