Shell MCP Server

Add secure shell command execution capabilities to your AI applications with the Shell MCP Server! Built for the Model Context Protocol.

Features

Secure Execution - Commands run only in specified directories
Multiple Shells - Support for bash, sh, cmd, powershell
Timeout Control - Automatic termination of long-running commands
Cross-Platform - Works on both Unix and Windows systems
Safe by Default - Built-in directory and shell validation

Quick Start

Installation

# Using pip
pip install shell-mcp-server

# Using uv (recommended)
uv pip install shell-mcp-server

Claude Desktop Integration

Add this to your Claude Desktop config to enable shell command execution:

Click to view configuration

{
    "mcpServers": {
        "shell-mcp-server": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/shell-mcp-server",
                "run",
                "shell-mcp-server",
                "/path/to/allowed/dir1",
                "/path/to/allowed/dir2",
                "--shell", "bash", "/bin/bash",
                "--shell", "zsh", "/bin/zsh"
            ]
        }
    }
}

Usage Examples

Basic File Operations

# List directory contents
result = execute_command(
    command="ls -la",
    shell="bash",
    cwd="/path/to/project"
)

# Find files by pattern
result = execute_command(
    command="find . -name '*.py'",
    shell="bash",
    cwd="/path/to/project"
)

Project Management

# Git operations
result = execute_command(
    command="git status && git diff",
    shell="bash",
    cwd="/path/to/repo"
)

# Package management
result = execute_command(
    command="pip list --outdated",
    shell="bash",
    cwd="/path/to/python/project"
)

System Information

# Resource usage
result = execute_command(
    command="df -h && free -h",
    shell="bash",
    cwd="/path/to/dir"
)

# Process monitoring
result = execute_command(
    command="ps aux | grep python",
    shell="bash",
    cwd="/path/to/dir"
)

File Processing

# Search file content
result = execute_command(
    command="grep -r 'TODO' .",
    shell="bash",
    cwd="/path/to/project"
)

# File manipulation
result = execute_command(
    command="awk '{print $1}' data.csv | sort | uniq -c",
    shell="bash",
    cwd="/path/to/data"
)

Windows-Specific Examples

# List processes
result = execute_command(
    command="Get-Process | Where-Object {$_.CPU -gt 10}",
    shell="powershell",
    cwd="C:\path\to\dir"
)

# System information
result = execute_command(
    command="systeminfo | findstr /B /C:'OS'",
    shell="cmd",
    cwd="C:\path\to\dir"
)

Configuration

Configure behavior with command-line arguments:

Argument	Description
`directories`	List of allowed directories
`--shell name path`	Shell specifications (name and path)

Environment variables:

COMMAND_TIMEOUT: Max execution time in seconds (default: 30)

Security Features

Directory Isolation: Commands can only execute in specified directories
Shell Control: Only configured shells are allowed
Timeout Protection: All commands have a configurable timeout
Path Validation: Working directory validation prevents traversal attacks
Permission Isolation: Commands run with the same permissions as the server process

Development

Set up your development environment:

# Create and activate virtual environment
uv venv
source .venv/bin/activate

# Install development dependencies
uv pip install -e ".[test]"

# Run tests
python -m pytest

# Run tests with coverage
python -m pytest --cov=shell_mcp_server