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

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

From source:

git clone https://github.com/sonirico/mcp-shell && cd mcp-shell
make install
mcp-shell

---

Configure it

Secure mode is the default. With no config file, mcp-shell boots in secure
mode restricted to a narrow allowlist of read-only utilities (ls, cat,
grep, find, head, tail, ...). You only need a config file to widen or
change that policy. To run fully unrestricted you must opt in explicitly:

MCP_SHELL_ALLOW_UNSAFE=true mcp-shell   # disables all validation - do not use in production

To customize the policy, point to a YAML config:

export MCP_SHELL_SEC_CONFIG_FILE=/path/to/security.yaml
mcp-shell

Secure mode (recommended) — no shell interpretation, executable allowlist only:

security:
  enabled: true
  use_shell_execution: false
  allowed_executables:
    - ls
    - cat
    - grep
    - find
    - echo
  # WARNING: never add shell/language interpreters (bash, sh, python, perl,
  # ruby, node) or alias-capable tools (git) here - the interpreter executes
  # whatever it is handed, bypassing secure mode entirely. mcp-shell warns at
  # startup if it finds one.
  blocked_patterns:          # optional: restrict args on allowed commands
    - '(^|\s)remote\s+(-v|--verbose)(\s|$)'
  max_execution_time: 30s
  max_output_size: 1048576
  working_directory: /tmp/mcp-workspace
  audit_log: true

Legacy mode — shell execution, allowlist/blocklist by command string (vulnerable to injection if not careful):

security:
  enabled: true
  use_shell_execution: true
  allowed_commands: [ls, cat, grep, echo]
  blocked_patterns: ['rm\s+-rf', 'sudo\s+']
  max_execution_time: 30s
  audit_log: true

---

Wire it up

Claude Desktop — add to your MCP config:

{
  "mcpServers": {
    "shell": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "sonirico/mcp-shell:latest"],
      "env": { "MCP_SHELL_LOG_LEVEL": "info" }
    }
  }
}

For custom config, mount the file and set the env:

{
  "command": "docker",
  "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"]
}

---

Tool API

| Parameter | Type | Description |
|-----------|------|-------------|
| command | string | Shell command to run (required) |
| base64 | boolean | Encode stdout/stderr as base64 (default: false) |

Response includes status, exit_code, stdout, stderr, command, execution_time, and optional security_info.

---

Environment variables

| Variable | Description |
|----------|-------------|
| MCP_SHELL_SEC_CONFIG_FILE | Path to security YAML (overrides built-in secure defaults) |
| MCP_SHELL_ALLOW_UNSAFE | Set true to disable all validation and run unrestricted (opt-in) |
| MCP_SHELL_SERVER_NAME | Server name (default: "mcp-shell 🐚") |
| MCP_SHELL_LOG_LEVEL | debug, info, warn, error, fatal |
| MCP_SHELL_LOG_FORMAT | json, console |
| MCP_SHELL_LOG_OUTPUT | stdout, stderr, file |

---

Development

make install dev-tools   # deps + goimports, golines
make fmt test lint
make docker-build       # build image locally
make release            # binary + docker image

---

Security

- Default: Secure mode, restricted to a narrow allowlist of read-only utilities. No interpreters.
- Secure mode (use_shell_execution: false): the command is parsed into a shell AST and only a single, fully-literal simple command is accepted (no pipes, lists, substitution, redirection or globs); its executable must be on the allowlist. Interpreters (bash/sh/python) are hard-denied even if allowlisted, and per-tool policies strip escape hatches (git -c, find -exec, tar --checkpoint-action). This is an early-reject layer, not a sandbox.
- Unrestricted: Only via MCP_SHELL_ALLOW_UNSAFE=true. Full access; fine for local dev, dangerous otherwise.
- 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.

---

Contributing

Fork, branch, make fmt test, open a PR.