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

Security is off by default. To enable it, 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
    - /usr/bin/git
  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
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: No restrictions. Commands run with full access. Fine for local dev; dangerous otherwise.
• Secure mode (use_shell_execution: false): Executable allowlist, no shell parsing. Blocks injection.
• Docker: Runs as non-root, Alpine-based. Use it in production.

---

Contributing

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