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. 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-a
Add this skill
npx mdskills install sonirico/mcp-shellWell-documented shell execution MCP server with strong security features and clear setup instructions
1# mcp-shell 🐚2[](https://archestra.ai/mcp-catalog/sonirico__mcp-shell)34A 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.56> 🧠💥🖥️ *Think of `mcp-shell` as the command-line actuator for your LLM.*7> While language models reason about the world, `mcp-shell` is what lets them **touch it**.89<a href="https://glama.ai/mcp/servers/@sonirico/mcp-shell">10 <img width="380" height="200" src="https://glama.ai/mcp/servers/@sonirico/mcp-shell/badge" alt="mcp-shell MCP server" />11</a>1213## What is this?1415This 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.1617Built on top of the official MCP SDK for Go: [mark3labs/mcp-go](https://github.com/mark3labs/mcp-go).1819It'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.2021Out 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.2223## Features2425- **🔒 Security First**: Configurable command allowlists, blocklists, and execution constraints26- **🐳 Docker Ready**: Lightweight Alpine-based container for secure isolation27- **📊 Structured Responses**: JSON-formatted output with stdout, stderr, exit codes, and execution metadata28- **🔄 Binary Data Support**: Optional base64 encoding for handling binary command output29- **⚡ Performance Monitoring**: Execution time tracking and resource limits30- **📋 Audit Logging**: Complete command execution audit trail with structured logging31- **🎯 Context Aware**: Supports command execution with proper context cancellation32- **⚙️ Environment Configuration**: Full configuration via environment variables3334## Security Features3536- **Command Validation**: Allowlist/blocklist with regex pattern matching37- **Execution Limits**: Configurable timeouts and output size limits38- **User Isolation**: Run commands as unprivileged users39- **Working Directory**: Restrict execution to specific directories40- **Audit Trail**: Complete logging of all command executions41- **Resource Limits**: Memory and CPU usage constraints4243## Quick Start4445### Prerequisites4647- Go 1.23 or later48- Unix-like system (Linux, macOS, WSL)49- Docker (optional, for containerized deployment)5051### Installation5253```bash54git clone https://github.com/sonirico/mcp-shell55cd mcp-shell56make install57```5859### Basic Usage6061```bash62# Run with default configuration (if installed system-wide)63mcp-shell6465# Or run locally66make run6768# Run with security enabled (creates temporary config)69make run-secure7071# Run with custom config file72MCP_SHELL_SEC_CONFIG_FILE=security.json mcp-shell7374# Run with environment overrides75MCP_SHELL_LOG_LEVEL=debug mcp-shell76```7778### Docker Deployment (Recommended)7980```bash81# Build Docker image82make docker-build8384# Run in secure container85make docker-run-secure8687# Run with shell access for debugging88make docker-shell89```9091## Configuration9293### Environment Variables9495Basic server and logging configuration via environment variables:9697#### Server Configuration9899- `MCP_SHELL_SERVER_NAME`: Server name (default: "mcp-shell 🐚")100- `MCP_SHELL_VERSION`: Server version (set at compile time)101102#### Logging Configuration103104- `MCP_SHELL_LOG_LEVEL`: Log level (debug, info, warn, error, fatal)105- `MCP_SHELL_LOG_FORMAT`: Log format (json, console)106- `MCP_SHELL_LOG_OUTPUT`: Log output (stdout, stderr, file)107108#### Configuration File109110- `MCP_SHELL_SEC_CONFIG_FILE`: Path to YAML configuration file111112### Security Configuration (YAML Only)113114Security settings are configured exclusively via YAML configuration file:115116```bash117export MCP_SHELL_SEC_CONFIG_FILE=security.yaml118```119120Example security configuration file:121122```yaml123security:124 enabled: true125 allowed_commands:126 - ls127 - cat128 - grep129 - find130 - echo131 blocked_commands:132 - rm -rf133 - sudo134 - chmod135 blocked_patterns:136 - 'rm\s+.*-rf.*'137 - 'sudo\s+.*'138 max_execution_time: 30s139 working_directory: /tmp/mcp-workspace140 max_output_size: 1048576141 audit_log: true142```143144## Tool Parameters145146- `command` (string, required): Shell command to execute147- `base64` (boolean, optional): Return stdout/stderr as base64-encoded strings148149## Response Format150151```json152{153 "status": "success|error",154 "exit_code": 0,155 "stdout": "command output",156 "stderr": "error output",157 "command": "executed command",158 "execution_time": "100ms",159 "security_info": {160 "security_enabled": true,161 "working_dir": "/tmp/mcp-workspace",162 "timeout_applied": true163 }164}165```166167## Integration Examples168169### With Claude Desktop170171```json172{173 "mcpServers": {174 "shell": {175 "command": "docker",176 "args": ["run", "--rm", "-i", "mcp-shell:latest"],177 "env": {178 "MCP_SHELL_SECURITY_ENABLED": "true",179 "MCP_SHELL_LOG_LEVEL": "info"180 }181 }182 }183}184```185186### Production Deployment187188```bash189# Build and install190make build191sudo make install-bin192193# Set environment variables for basic config194export MCP_SHELL_LOG_LEVEL=info195export MCP_SHELL_LOG_FORMAT=json196export MCP_SHELL_SEC_CONFIG_FILE=/etc/mcp-shell/config.json197198# Security is configured in the JSON file only199# Run service200mcp-shell201```202203## Development204205```bash206# Install dependencies and dev tools207make install dev-tools208209# Format code210make fmt211212# Run tests213make test214215# Run linter216make lint217218# Build for release219make release220221# Generate config example222make config-example223```224225## Security Considerations226227### ⚠️ Important Security Notes2282291. **Default Mode**: Runs with **full system access** when security is disabled (which is, of course, a terrible idea — unless you're into that).2302. **Container Isolation**: Use Docker deployment for additional security layers2313. **User Privileges**: Run as non-root user in production2324. **Network Access**: Commands can access network unless explicitly restricted2335. **File System**: Can read/write files based on user permissions234235### Recommended Production Setup236237Create `security.yaml`:238239```yaml240security:241 enabled: true242 allowed_commands:243 - ls244 - cat245 - head246 - tail247 - grep248 - find249 - wc250 - sort251 - uniq252 blocked_patterns:253 - 'rm\s+.*-rf.*'254 - 'sudo\s+.*'255 - 'chmod\s+(777|666)'256 - '>/dev/'257 - 'curl.*\|.*sh'258 max_execution_time: 10s259 working_directory: /tmp/mcp-workspace260 max_output_size: 524288261 audit_log: true262```263264Set environment:265```bash266export MCP_SHELL_SEC_CONFIG_FILE=security.yaml267export MCP_SHELL_LOG_LEVEL=info268export MCP_SHELL_LOG_FORMAT=json269```270271## Contributing2722731. Fork the repository2742. Create feature branch (`git checkout -b feature/amazing-feature`)2753. Commit changes (`git commit -m 'Add amazing feature'`)2764. Push to branch (`git push origin feature/amazing-feature`)2775. Open Pull Request278279Ensure code is formatted (`make fmt`) and passes tests (`make test`).280281## License282283MIT License - See LICENSE file for details.
Full transparency — inspect the skill content before installing.