Skillget

mcp-shell

mcp
Security Audit
Pass
Health Pass
  • License — License: GPL-3.0
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Community trust — 75 GitHub stars
Code Pass
  • Code scan — Scanned 3 files during light audit, no dangerous patterns found
Permissions Pass
  • Permissions — No dangerous permissions requested
Purpose
This tool acts as a Model Context Protocol (MCP) server that allows AI models to execute shell commands on demand. It provides a controlled interface so you can dictate exactly what commands your AI assistant is permitted to run.

Security Assessment
The core function of this server is executing shell commands, which naturally carries significant risk. However, the tool is built with strong safety guardrails. It defaults to a secure mode that strictly enforces an allowlist of executables without invoking a system shell, effectively neutralizing shell injection attacks. The codebase scan passed with no dangerous patterns, hardcoded secrets, or malicious network requests detected. That said, because security is disabled by default when launching the server, users must actively configure and mount the YAML security file to be protected. If users run the container without this configuration or use the "legacy mode" (which enables shell interpretation), the risk escalates severely. Overall risk: Medium (context-dependent).

Quality Assessment
The project is actively maintained, with its most recent push occurring today. It is licensed under GPL-3.0 and has garnered 75 GitHub stars, indicating a solid baseline of community trust. The automated code scan evaluated 3 files and found no issues, confirming a clean and lightweight codebase.

Verdict
Use with caution — inherently safe if you strictly apply the secure execution YAML configuration, but dangerous if deployed without it.
SUMMARY

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

README.md

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

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.

Reviews (0)

No results found