What is Shell Mcp Server

The shell-mcp-server is a secure shell command execution server designed for Claude AI, enabling controlled access to shell commands within specified directories.

Use cases

Use cases include basic file operations, project management tasks, system information retrieval, file processing, and Windows-specific command execution.

How to use

To use shell-mcp-server, install it via pip or uv, configure it in your Claude Desktop settings, and execute shell commands using the provided API in your applications.

Key features

Key features include secure execution in specified directories, support for multiple shell types (bash, sh, cmd, powershell), timeout control for commands, cross-platform compatibility, and built-in safety measures for directory and shell validation.

Where to use

Shell-mcp-server is suitable for AI applications that require secure command execution, particularly in environments where controlled access to the shell is necessary.

🖥️ 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:

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

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

🤝 Contributing

Contributions are welcome! Feel free to:

• 🐛 Report bugs
• 💡 Suggest features
• 🔧 Submit pull requests
• 📚 Improve documentation

📜 License

MIT License - see LICENSE for details.