Which integrations are available for this server?

Supports containerized deployment for secure isolation of shell command execution Supports command execution on Unix-like systems including Linux Supports command execution on macOS operating system Provides secure shell command execution capabilities with configurable security constraints, command validation, and execution limits

How do I use mcp-shell?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-shell list files in the current directory" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mcp-shell

Trust Score glama

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

Related MCP server: Lilith 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.