sonirico/mcp-shell

MCP server that runs shell commands. Your LLM gets a tool; you get control over what runs and how.
Built on mark3labs/mcp-go. Written in Go.
---
Run it
**Docker** (easiest):
**From source**:
---
Configure it
**Secure mode is the default.** With no config file, mcp-shell boots in secure
mode and registers only typed tools: file reads, grep/glob, git inspection,
and (opt-in) file/git writes and operator-defined scripts. There is no raw
shell command. You only need a config file to change the defaults below. To
run fully unrestricted you must opt in explicitly:
To customize the policy, point to a YAML config:
**Secure mode** (default) — typed tools only, every path confined to working_directory:
---
Wire it up
**Claude Desktop** — add to your MCP config:
For custom config, mount the file and set the env:
---
Tools
Secure mode (the default) registers these typed tools. * marks a required
parameter.
| Tool | Parameters | Available |
|------|------------|-----------|
| read_file | path*, offset, limit, tail | always |
| list_dir | path, depth, include_hidden | always |
| glob | pattern*, path, newer_than, max_results | always |
| grep | pattern*, path, glob, ignore_case, context, files_only, count, max_results | always |
| stat | path* | always |
| diff_files | path_a*, path_b* | always |
| system_info | | always |
| git_status | | always |
| git_log | max_count, ref, path, author, grep, since, until, oneline, follow | always |
| git_diff | ref, ref_to, staged, path, stat_only, name_only | always |
| git_show | ref, path, stat_only | always |
| git_blame | path*, ref, line_start, line_end | always |
| git_branches | all, merged | always |
| git_tags | pattern | always |
| git_rev_parse | ref* | always |
| git_ls_files | path, untracked | always |
| git_stash_list | | always |
| git_remotes | | always |
| write_file | path*, content*, append | writes_enabled |
| edit_file | path*, old_string*, new_string*, replace_all | writes_enabled |
| mkdir | path* | writes_enabled |
| move | from*, to* | writes_enabled |
| delete | path*, recursive | writes_enabled |
| git_add | paths, all | writes_enabled |
| git_commit | message*, all | writes_enabled |
| git_switch | branch*, create | writes_enabled |
| git_restore | paths*, staged | writes_enabled |
| git_stash | action*, message | writes_enabled |
| run_script | name* | scripts |
Every path parameter is resolved against working_directory (symlinks
followed); anything outside it is rejected. Git paths and refs are passed
positionally and validated: a ref starting with - is rejected. There are no
network tools; push, fetch and clone are not offered.
**Unrestricted mode**: shell_exec exists only with MCP_SHELL_ALLOW_UNSAFE=1, runs the command through bash -c with no validation, by design, and it is the only tool registered in that mode.
---
Environment variables
| Variable | Description |
|----------|-------------|
| MCP_SHELL_SEC_CONFIG_FILE | Path to security YAML (overrides built-in secure defaults) |
| MCP_SHELL_ALLOW_UNSAFE | Set 1 (or true) to disable secure mode and expose shell_exec instead of the typed tools (opt-in) |
| MCP_SHELL_SERVER_NAME | Server name (default: "mcp-shell 🐚") |