Content
# mcp-shell 🐚
[](https://archestra.ai/mcp-catalog/sonirico__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](https://github.com/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
1. **Default Mode**: Runs with **full system access** when security is disabled (which is, of course, a terrible idea — unless you're into that).
2. **Container Isolation**: Use Docker deployment for additional security layers
3. **User Privileges**: Run as non-root user in production
4. **Network Access**: Commands can access network unless explicitly restricted
5. **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
1. Fork the repository
2. Create feature branch (`git checkout -b feature/amazing-feature`)
3. Commit changes (`git commit -m 'Add amazing feature'`)
4. Push to branch (`git push origin feature/amazing-feature`)
5. Open Pull Request
Ensure code is formatted (`make fmt`) and passes tests (`make test`).
## License
MIT License - See LICENSE file for details.
