mcp-shell

A secure Model Context Protocol (MCP) server for AI-driven shell command execution.

Stars

Forks

Watchers

Issues

mcp-shell enables AI assistants and MCP clients to securely execute shell commands via the standardized Model Context Protocol. Built in Go and leveraging the official MCP SDK, it facilitates structured, auditable, and context-aware access to shell environments. The server emphasizes security through Docker isolation, command validation, resource limits, and comprehensive audit logging.

Key Features

Configurable command allowlists and blocklists

Docker-based isolated execution environment

Structured JSON output for command results

Base64 support for binary output

Execution time and resource usage monitoring

Complete audit logging of all command executions

Context cancellation for command execution

Environment variable configuration

User privilege isolation

Support for configuration via YAML

Use Cases

Secure shell command execution for AI assistants

Automating system administration tasks through AI agents

Building auditable AI toolchains with shell access

Remote command execution with strong security controls

Integrating shell access into LLM-powered workflows

Confining and monitoring AI-driven shell operations

Context-aware tool invocation for autonomous agents

Providing a controlled environment for experiments with AI reasoning

Running tool-enhanced LLM applications in isolated containers

Supporting safe integration of third-party tools into AI ecosystems

README

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

bash

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

Basic Usage

bash

# 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)

bash

# 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:

bash

export MCP_SHELL_SEC_CONFIG_FILE=security.yaml

Example security configuration file:

yaml

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

json

{
  "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

json

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

Production Deployment

bash

# 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

bash

# 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:

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:

bash

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.

Star History

Repository Owner

sonirico

User

Repository Details

Language Go

Default Branch master

Size 53 KB

Contributors 2

License MIT License

MCP Verified Nov 11, 2025

Programming Languages

74.34%

Makefile

17.85%

Dockerfile

7.81%

Topics

ai bash go llm mcp model-context-protocol os-exec shell terminal

Join Our Newsletter

Stay updated with the latest AI tools, news, and offers by subscribing to our weekly newsletter.

Related MCPs

Discover similar Model Context Protocol servers

MCP Shell Server

A secure, configurable shell command execution server implementing the Model Context Protocol.

MCP Shell Server provides secure remote execution of whitelisted shell commands via the Model Context Protocol (MCP). It supports standard input, command output retrieval, and enforces strict safety checks on command operations. The tool allows configuration of allowed commands and execution timeouts, and can be integrated with platforms such as Claude.app and Smithery. With robust security assessments and flexible deployment methods, it facilitates controlled shell access for AI agents.

⭐ 153
MCP
tumf/mcp-shell-server

SSH MCP Server

MCP-compliant SSH server for secure command execution on Linux and Windows.

SSH MCP Server provides an MCP-compliant interface to expose SSH control for both Linux and Windows systems. It enables secure execution of shell commands remotely, supporting password and SSH key authentication as well as sudo and su elevation. Built with TypeScript and the official MCP SDK, the server offers configurable timeouts, process management, and compatibility with popular LLM clients such as Claude Desktop and Cursor. Designed for robust and flexible integration, it facilitates natural language interfaces to system administration tasks.

⭐ 137
MCP
tufantunc/ssh-mcp

CMD MCP Server

Execute CMD commands via the Model Context Protocol with cross-platform and SSH support.

CMD MCP Server is an implementation of the Model Context Protocol (MCP) for executing CMD commands on Windows and Linux systems, with additional support for SSH connections. It enables seamless integration of command-line operations with MCP-compatible applications, leveraging the official MCP SDK. Written in TypeScript for cross-platform compatibility, it allows programmatic execution, configuration, and extension of CMD operations through standardized protocols. The server is designed for easy installation, robust configuration, and developer-friendly extension.

⭐ 22
MCP
PhialsBasement/CMD-MCP-Server

just-mcp

A production-ready MCP server for Justfile command integration with LLMs.

just-mcp delivers an MCP (Model Context Protocol) server that enables seamless integration between AI assistants and the Just command runner. It provides functionality for AI models to discover, execute, and introspect Justfile recipes using a standardized protocol. The system emphasizes context abstraction, safer command execution compared to raw bash, and user-friendly interfaces for both agents and humans. Built-in safety and validation features further enhance reliability and security.

⭐ 31
MCP
PromptExecution/just-mcp

mcp-code-runner

A Docker-based code runner implementing the MCP protocol

mcp-code-runner is a code execution service built on top of the Model Context Protocol (MCP). It enables users to execute code securely within Docker containers and retrieve the execution results. The tool is designed to support code execution use cases while adhering to the MCP standard for interoperability. A local Docker environment is required for operation.

⭐ 14
MCP
axliupore/mcp-code-runner

wcgw

Local shell and code agent server with deep AI integration for Model Context Protocol clients.

wcgw is an MCP server that empowers conversational AI models, such as Claude, with robust shell command execution and code editing capabilities on the user's local machine. It offers advanced tools for syntax-aware file editing, interactive shell command handling, and context management to optimize AI-driven workflows. Key protections are included to safeguard files, prevent accidental overwrites, and streamline large file handling, ensuring smooth automated code development and execution.

⭐ 616
MCP
rusiaaman/wcgw

View all Alternatives

Didn't find tool you were looking for?

Search AI Tools

mcp-shell

Key Features

Use Cases

README

mcp-shell 🐚

What is this?

Features

Security Features

Quick Start

Prerequisites

Installation

Basic Usage

Docker Deployment (Recommended)

Configuration

Environment Variables

Server Configuration

Logging Configuration

Configuration File

Security Configuration (YAML Only)

Tool Parameters

Response Format

Integration Examples

With Claude Desktop

Production Deployment

Development

Security Considerations

⚠️ Important Security Notes

Recommended Production Setup

Contributing

License

Star History

Repository Owner

Repository Details

Programming Languages

Tags

Topics

Related MCPs