mcp-shell

mcp-shell 🐚

A robust Model Context Protocol (MCP) server that provides secure shell command execution capabilities to AI assistants and other MCP clients. In other words: the brain thinks, this runs the commands.

🧠💥🖥️ Think of mcp-shell as the command-line actuator for your LLM. While language models reason about the world, mcp-shell is what lets them touch it.

What is this?

This tool creates a bridge between AI systems and your shell environment through the standardized MCP protocol. It exposes the system shell as a structured tool, enabling autonomous workflows, tool-assisted reasoning, and real-world problem solving.

Built on top of the official MCP SDK for Go: mark3labs/mcp-go.

It's written in Go, integrates directly with mcp-go, and provides a clean path from thought to execution. I'm aware similar projects exist — this one’s mine. It solves the problem the way I want it solved: minimal, composable, auditable.

Out of the box it runs isolated via Docker, but that's just a start. The roadmap includes support for optional jailing mechanisms like chroot, namespaces, and syscall-level confinement — without depending on Docker for everything.

Features

🔒 Security First: Configurable command allowlists, blocklists, and execution constraints
🐳 Docker Ready: Lightweight Alpine-based container for secure isolation
📊 Structured Responses: JSON-formatted output with stdout, stderr, exit codes, and execution metadata
🔄 Binary Data Support: Optional base64 encoding for handling binary command output
⚡ Performance Monitoring: Execution time tracking and resource limits
📋 Audit Logging: Complete command execution audit trail with structured logging
🎯 Context Aware: Supports command execution with proper context cancellation
⚙️ Environment Configuration: Full configuration via environment variables

Security Features

Command Validation: Allowlist/blocklist with regex pattern matching
Execution Limits: Configurable timeouts and output size limits
User Isolation: Run commands as unprivileged users
Working Directory: Restrict execution to specific directories
Audit Trail: Complete logging of all command executions
Resource Limits: Memory and CPU usage constraints

Quick Start

Prerequisites

Go 1.23 or later
Unix-like system (Linux, macOS, WSL)
Docker (optional, for containerized deployment)

Installation

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

Basic Usage

# Run with default configuration (if installed system-wide)
mcp-shell

# Or run locally
make run

# Run with security enabled (creates temporary config)
make run-secure

# Run with custom config file
MCP_SHELL_SEC_CONFIG_FILE=security.json mcp-shell

# Run with environment overrides
MCP_SHELL_LOG_LEVEL=debug mcp-shell

Docker Deployment (Recommended)

# Build Docker image
make docker-build

# Run in secure container
make docker-run-secure

# Run with shell access for debugging
make docker-shell

Configuration

Environment Variables

Basic server and logging configuration via environment variables:

Server Configuration

MCP_SHELL_SERVER_NAME: Server name (default: "mcp-shell 🐚")
MCP_SHELL_VERSION: Server version (set at compile time)

Logging Configuration

MCP_SHELL_LOG_LEVEL: Log level (debug, info, warn, error, fatal)
MCP_SHELL_LOG_FORMAT: Log format (json, console)
MCP_SHELL_LOG_OUTPUT: Log output (stdout, stderr, file)

Configuration File

MCP_SHELL_SEC_CONFIG_FILE: Path to YAML configuration file

Security Configuration (YAML Only)

Security settings are configured exclusively via YAML configuration file:

export MCP_SHELL_SEC_CONFIG_FILE=security.yaml

Example security configuration file:

security:
  enabled: true
  allowed_commands:
    - ls
    - cat
    - grep
    - find
    - echo
  blocked_commands:
    - rm -rf
    - sudo
    - chmod
  blocked_patterns:
    - 'rm\s+.*-rf.*'
    - 'sudo\s+.*'
  max_execution_time: 30s
  working_directory: /tmp/mcp-workspace
  max_output_size: 1048576
  audit_log: true

Tool Parameters

command (string, required): Shell command to execute
base64 (boolean, optional): Return stdout/stderr as base64-encoded strings

Response Format

{
  "status": "success|error",
  "exit_code": 0,
  "stdout": "command output",
  "stderr": "error output", 
  "command": "executed command",
  "execution_time": "100ms",
  "security_info": {
    "security_enabled": true,
    "working_dir": "/tmp/mcp-workspace",
    "timeout_applied": true
  }
}

Integration Examples

With Claude Desktop

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

Production Deployment

# Build and install
make build
sudo make install-bin

# Set environment variables for basic config
export MCP_SHELL_LOG_LEVEL=info
export MCP_SHELL_LOG_FORMAT=json
export MCP_SHELL_SEC_CONFIG_FILE=/etc/mcp-shell/config.json

# Security is configured in the JSON file only
# Run service
mcp-shell

Development

# Install dependencies and dev tools
make install dev-tools

# Format code
make fmt

# Run tests
make test

# Run linter
make lint

# Build for release
make release

# Generate config example
make config-example

Security Considerations

⚠️ Important Security Notes

Default Mode: Runs with full system access when security is disabled (which is, of course, a terrible idea — unless you're into that).
Container Isolation: Use Docker deployment for additional security layers
User Privileges: Run as non-root user in production
Network Access: Commands can access network unless explicitly restricted
File System: Can read/write files based on user permissions

Recommended Production Setup

Create security.yaml:

security:
  enabled: true
  allowed_commands:
    - ls
    - cat
    - head
    - tail
    - grep
    - find
    - wc
    - sort
    - uniq
  blocked_patterns:
    - 'rm\s+.*-rf.*'
    - 'sudo\s+.*'
    - 'chmod\s+(777|666)'
    - '>/dev/'
    - 'curl.*\|.*sh'
  max_execution_time: 10s
  working_directory: /tmp/mcp-workspace
  max_output_size: 524288
  audit_log: true

Set environment:

export MCP_SHELL_SEC_CONFIG_FILE=security.yaml
export MCP_SHELL_LOG_LEVEL=info
export MCP_SHELL_LOG_FORMAT=json

Contributing

Fork the repository
Create feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open Pull Request

Ensure code is formatted (make fmt) and passes tests (make test).

License

MIT License - See LICENSE file for details.

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

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

Related MCP Servers

MCP Terminal
sichang824
A
security
A
license
A
quality
A server that enables AI assistants to execute terminal commands and retrieve outputs via the Model Context Protocol (MCP).
Last updated -
3
14
Python
MIT License
Lilith Shell
charles-adedotun
-
security
A
license
-
quality
An enhanced MCP server that grants AI assistants the ability to execute terminal commands on a user's system with improved security controls, designed for use in controlled environments.
Last updated -
Python
MIT License
MCP Shell Server
mkusaka
A
security
A
license
A
quality
A server that uses the Model Context Protocol (MCP) to allow AI agents to safely execute shell commands on a host system.
Last updated -
1
17
4
TypeScript
MIT License
Terminal MCP Server
weidwonder
A
security
F
license
A
quality
An MCP server that allows AI models to execute system commands on local machines or remote hosts via SSH, supporting persistent sessions and environment variables.
Last updated -
1
451
17
TypeScript

View all related MCP servers