MC
Code Execution

MCP Server Shell: Secure, Auditable AI Command Execution

Execute shell commands securely and auditably with MCP server, giving AI controlled, on-demand command access and complete logs.

View on GitHub
Quick Install
npx -y @sonirico/mcp-shell

Overview

MCP Server Shell is a minimal server that exposes a controlled shell interface as an MCP (Model Context Protocol) tool. It enables AI agents to run shell commands on-demand while enforcing safety controls and producing full, tamper-evident audit logs. Instead of giving an LLM unrestricted SSH access or passwordless sudo, MCP Server Shell provides a guarded, observable bridge: the model requests a command, the server validates and executes it in a constrained environment, and the result — together with metadata and operators’ decisions — is recorded.

This model is useful when you want automated or human-assisted agents to operate on real systems but need to keep operations auditable and secure. Typical scenarios include debug sessions driven by an assistant, controlled automation in CI/CD pipelines, or triage workflows where the assistant can request facts from the host but cannot escalate privileges or perform unbounded changes.

Features

  • Exposes a shell tool via the MCP protocol so LLMs can discover and call it
  • Command validation: whitelists, blacklists or pattern rules to restrict allowed commands
  • Execution constraints: timeouts, CPU/memory limits, working-directory and user isolation
  • Auditable logs: full input, stdout/stderr, exit codes, timestamps and execution metadata
  • Dry-run / preview mode to show what would run without making changes
  • Integration-friendly: configurable auth tokens and TLS for secure connections
  • Minimal footprint: designed to be embedded in automation pipelines or hosted as a small service

Installation / Configuration

The project is hosted on GitHub; clone the repository and run the included container or build from source.

Clone the repo (example):

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

Run with Docker (example):

# Example environment variables shown — adjust for your deployment
docker run -d \
  -p 8080:8080 \
  -e MCP_PORT=8080 \
  -e AUTH_TOKEN=your-secret-token \
  -e COMMAND_WHITELIST="ls,cat,tail,journalctl" \
  -v /var/log:/host/log:ro \
  --name mcp-shell sonirico/mcp-shell:latest

Build and run from source (example steps):

# If the repo provides a build script or Makefile, use it. Example:
make build
./mcp-shell --config ./config.yaml

Example config.yaml (replace keys with your desired values):

server:
  listen: "0.0.0.0:8080"
  tls: false

auth:
  token: "your-secret-token"

security:
  command_wh
Tags:code-execution