mcp-shell MCP Server

How to use

You can connect to this MCP server from an MCP client and send shell command requests. Each request specifies a command to run and can request that stdout and stderr be encoded as base64 if needed. The server returns a structured response including status, exit code, the command that was run, execution time, and any security information.

How to install

Prerequisites you need before starting: Docker installed on your machine. You will run the MCP server either from a prebuilt Docker image or by building from source.

Option 1 – Run with Docker (easiest):

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

Option 2 – Build and run from source:

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

Additional content

Security defaults are intentionally broad to support local development. You can enable a security configuration to restrict execution and enforce an allowlist. The recommended secure mode disables shell interpretation and only permits specific executables. You can also use legacy mode to allow shell execution with command-based restrictions, but this mode is more vulnerable to injection if not carefully managed.

Security and configuration notes

- Default behavior: no restrictions. Commands run with full access, suitable for local development but risky in production.

- Secure mode (recommended): shell execution is disabled, only allowed executables can run, and arguments can be restricted.

- Docker deployment: run the server in a container with a non-root user inside an Alpine-based image for safer production use.

Configuration examples

Secure mode example — executable allowlist and no shell parsing:

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 example — shell execution with command-based restrictions (less safe):

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

How the MCP server is wired

To connect from an MCP client, you can configure a local stdio server that uses Docker to run the mcp-shell container. Use the following example to integrate into your MCP client configuration.

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

Environment variables

The server recognizes several environment variables to customize its behavior. The most common are listed below.

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

If you are developing or contributing, you can install development tools and run checks to keep the codebase healthy.

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

Notes on tooling and capabilities

The server exposes a simple tool API for executing shell commands. Each request can specify whether to base64-encode outputs and will receive structured results including status, exit code, stdout, stderr, the invoked command, and execution time.

shell_command

Executes a shell command and returns a structured result including status, exit code, stdout, stderr, the command, execution_time, and optional security_info.