mcp-shell 🐚

Trust Score

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 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?

Related Resources

GitHub Repository

Need Help?

Report Issue

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
19
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 -
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
31
6
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 -
420
1
16
24

View all related MCP servers

Appeared in Searches

How to use the terminal or command line interface

mcp-shell