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

hljs language-bash

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

From source:

hljs language-bash

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:

hljs language-bash

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

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

hljs language-yaml

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

hljs language-yaml

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:

hljs language-json

{
  "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:

hljs language-json

{
  "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

hljs language-bash

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.

mcp-shell

mcp-shell

Run it

Configure it

Wire it up

Tool API

Environment variables

Development

Security

Contributing

Similar Packages

Repository

Tags

Original Author

Publisher

Repository