Skip to content
Back to search

mcp-shell

Give hands to AI. MCP server to run shell commands securely, auditably, and on demand.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sonirico--mcp-shell/badge.svg)](/listings/sonirico--mcp-shell)

HTML

<a href="/listings/sonirico--mcp-shell"><img src="/api/listings/sonirico--mcp-shell/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 220 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # mcp-shell
  2. [![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/sonirico/mcp-shell)](https://archestra.ai/mcp-catalog/sonirico__mcp-shell)
  3. [![glama](https://glama.ai/mcp/servers/@sonirico/mcp-shell/badge)](https://glama.ai/mcp/servers/@sonirico/mcp-shell)
  4. MCP server that runs shell commands. Your LLM gets a tool; you get control over what runs and how.
  5. Built on [mark3labs/mcp-go](https://github.com/mark3labs/mcp-go). Written in Go.
  6. ---
  7. ## Run it
  8. **Docker** (easiest):
  9. ```bash
  10. docker run -it --rm -v /tmp/mcp-workspace:/tmp/mcp-workspace sonirico/mcp-shell:latest
  11. ```
  12. **From source**:
  13. ```bash
  14. git clone https://github.com/sonirico/mcp-shell && cd mcp-shell
  15. make install
  16. mcp-shell
  17. ```
  18. ---
  19. ## Configure it
  20. **Secure mode is the default.** With no config file, `mcp-shell` boots in secure
  21. mode and registers only typed tools: file reads, `grep`/`glob`, git inspection,
  22. and (opt-in) file/git writes and operator-defined scripts. There is no raw
  23. shell command. You only need a config file to change the defaults below. To
  24. run fully unrestricted you must opt in explicitly:
  25. ```bash
  26. MCP_SHELL_ALLOW_UNSAFE=1 mcp-shell # disables secure mode; the only tool is shell_exec
  27. ```
  28. To customize the policy, point to a YAML config:
  29. ```bash
  30. export MCP_SHELL_SEC_CONFIG_FILE=/path/to/security.yaml
  31. mcp-shell
  32. ```
  33. **Secure mode** (default) — typed tools only, every path confined to `working_directory`:
  34. ```yaml
  35. security:
  36. enabled: true
  37. working_directory: /tmp/mcp-workspace
  38. max_execution_time: 30s
  39. max_output_size: 1048576
  40. run_as_user: ""
  41. audit_log: true
  42. # Expose file and git write tools (write_file, edit_file, mkdir, move,
  43. # delete, git_add, git_commit, git_switch, git_restore, git_stash). Off by
  44. # default.
  45. writes_enabled: false
  46. # Operator-defined scripts exposed through the run_script tool. The client
  47. # picks a name; the argv is yours and cannot be altered.
  48. # scripts:
  49. # test: ["go", "test", "./..."]
  50. # lint: ["golangci-lint", "run"]
  51. ```
  52. ---
  53. ## Wire it up
  54. **Claude Desktop** — add to your MCP config:
  55. ```json
  56. {
  57. "mcpServers": {
  58. "shell": {
  59. "command": "docker",
  60. "args": ["run", "--rm", "-i", "sonirico/mcp-shell:latest"],
  61. "env": { "MCP_SHELL_LOG_LEVEL": "info" }
  62. }
  63. }
  64. }
  65. ```
  66. For custom config, mount the file and set the env:
  67. ```json
  68. {
  69. "command": "docker",
  70. "args": ["run", "--rm", "-i", "-v", "/path/to/security.yaml:/etc/mcp-shell/security.yaml", "-e", "MCP_SHELL_SEC_CONFIG_FILE=/etc/mcp-shell/security.yaml", "sonirico/mcp-shell:latest"]
  71. }
  72. ```
  73. ---
  74. ## Tools
  75. Secure mode (the default) registers these typed tools. `*` marks a required
  76. parameter.
  77. | Tool | Parameters | Available |
  78. |------|------------|-----------|
  79. | `read_file` | path*, offset, limit, tail | always |
  80. | `list_dir` | path, depth, include_hidden | always |
  81. | `glob` | pattern*, path, newer_than, max_results | always |
  82. | `grep` | pattern*, path, glob, ignore_case, context, files_only, count, max_results | always |
  83. | `stat` | path* | always |
  84. | `diff_files` | path_a*, path_b* | always |
  85. | `system_info` | | always |
  86. | `git_status` | | always |
  87. | `git_log` | max_count, ref, path, author, grep, since, until, oneline, follow | always |
  88. | `git_diff` | ref, ref_to, staged, path, stat_only, name_only | always |
  89. | `git_show` | ref, path, stat_only | always |
  90. | `git_blame` | path*, ref, line_start, line_end | always |
  91. | `git_branches` | all, merged | always |
  92. | `git_tags` | pattern | always |
  93. | `git_rev_parse` | ref* | always |
  94. | `git_ls_files` | path, untracked | always |
  95. | `git_stash_list` | | always |
  96. | `git_remotes` | | always |
  97. | `write_file` | path*, content*, append | writes_enabled |
  98. | `edit_file` | path*, old_string*, new_string*, replace_all | writes_enabled |
  99. | `mkdir` | path* | writes_enabled |
  100. | `move` | from*, to* | writes_enabled |
  101. | `delete` | path*, recursive | writes_enabled |
  102. | `git_add` | paths, all | writes_enabled |
  103. | `git_commit` | message*, all | writes_enabled |
  104. | `git_switch` | branch*, create | writes_enabled |
  105. | `git_restore` | paths*, staged | writes_enabled |
  106. | `git_stash` | action*, message | writes_enabled |
  107. | `run_script` | name* | scripts |
  108. Every path parameter is resolved against `working_directory` (symlinks
  109. followed); anything outside it is rejected. Git paths and refs are passed
  110. positionally and validated: a ref starting with `-` is rejected. There are no
  111. network tools; push, fetch and clone are not offered.
  112. **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.
  113. ---
  114. ## Environment variables
  115. | Variable | Description |
  116. |----------|-------------|
  117. | `MCP_SHELL_SEC_CONFIG_FILE` | Path to security YAML (overrides built-in secure defaults) |
  118. | `MCP_SHELL_ALLOW_UNSAFE` | Set `1` (or `true`) to disable secure mode and expose `shell_exec` instead of the typed tools (opt-in) |
  119. | `MCP_SHELL_SERVER_NAME` | Server name (default: "mcp-shell 🐚") |
  120. | `MCP_SHELL_LOG_LEVEL` | debug, info, warn, error, fatal |
  121. | `MCP_SHELL_LOG_FORMAT` | json, console |
  122. | `MCP_SHELL_LOG_OUTPUT` | stdout, stderr, file |
  123. ---
  124. ## Development
  125. ```bash
  126. make install dev-tools # deps + goimports, golines
  127. make fmt test lint
  128. make docker-build # build image locally
  129. make release # binary + docker image
  130. ```
  131. ---
  132. ## Security
  133. - **Default**: Secure mode. The server builds every command's argv itself; the
  134. client never supplies a shell string. Only typed tools are registered.
  135. - **Path confinement**: every path parameter is resolved against
  136. `working_directory`, symlinks followed, and anything that resolves outside
  137. it is rejected.
  138. - **Git hardening**: paths are passed after `--`, refs after
  139. `--end-of-options`, and a ref starting with `-` is rejected. Git runs with
  140. `GIT_CONFIG_NOSYSTEM=1`, `GIT_CONFIG_GLOBAL=/dev/null`, `core.fsmonitor`,
  141. `core.pager` and `core.hooksPath` neutralised, and `--no-ext-diff
  142. --no-textconv` on log/diff/show/blame.
  143. - **Minimal environment**: child processes get only `PATH`, `HOME` and `LANG`,
  144. never the server's own environment or `.env` secrets.
  145. - **Writes and scripts are opt-in**: `writes_enabled: true` exposes the
  146. file/git write tools; a non-empty `scripts` map exposes `run_script`. Both
  147. are off by default.
  148. - **Unrestricted**: only via `MCP_SHELL_ALLOW_UNSAFE=1`. The only tool
  149. registered is `shell_exec`, which runs `bash -c` with no validation. Fine
  150. for local dev, dangerous otherwise.
  151. - **Docker**: Runs as non-root, Alpine-based. Use it in production. Best paired with an OS sandbox (read-only FS, dropped caps) as defense-in-depth.
  152. Threat model, guarantees, and the scope for vulnerability reports live in [SECURITY.md](SECURITY.md). Read it before opening an advisory.
  153. ---
  154. ## Migrating from 0.x
  155. Secure mode no longer validates a `shell_exec` command string; it exposes
  156. typed tools instead. A config file's `security:` block no longer accepts:
  157. | Removed key | Replacement |
  158. |-------------|-------------|
  159. | `use_shell_execution` | not needed; typed tools never shell out |
  160. | `allowed_executables` | not needed; each tool runs a fixed, server-built argv |
  161. | `allowed_commands` | not needed; same as above |
  162. | `blocked_commands` | not needed; same as above |
  163. | `blocked_patterns` | not needed; same as above |
  164. Loading a config file that still sets one of these fails at startup with an
  165. error naming the key. There is no more "legacy mode" and no
  166. `security-legacy.yaml` example. If you need raw shell access, set
  167. `MCP_SHELL_ALLOW_UNSAFE=1` to get `shell_exec` back; it is no longer
  168. constrained by the `security:` block at all.
  169. ---
  170. ## Contributing
  171. Fork, branch, `make fmt test`, open a PR.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.