Shell MCP Server

🖥️ Shell MCP Server

🚀 ¡Añade capacidades de ejecución de comandos shell seguros a tus aplicaciones de IA con el Shell MCP Server! Construido para el Protocolo de Contexto de Modelos.

✨ Características

• 🔒 Ejecución Segura - Los comandos se ejecutan solo en directorios especificados
• 🐚 Múltiples Shells - Soporte para bash, sh, cmd, powershell
• ⏱️ Control de Tiempo de Espera - Terminación automática de comandos de larga duración
• 🌍 Multiplataforma - Funciona en sistemas Unix y Windows
• 🛡️ Seguro por Defecto - Validación integrada de directorios y shells

🚀 Inicio Rápido

Instalación

# Using pip
pip install shell-mcp-server

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

🔌 Integración con Claude Desktop

Añade esto a tu configuración de Claude Desktop para habilitar la ejecución de comandos shell:

{
    "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"
            ]
        }
    }
}

🎮 Ejemplos de Uso

Operaciones Básicas de Archivos

# 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"
)

Gestión de Proyectos

# 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"
)

Información del Sistema

# 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"
)

Procesamiento de Archivos

# 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"
)

Ejemplos Específicos para Windows

# 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"
)

⚙️ Configuración

Configura el comportamiento con argumentos de línea de comandos:

Variables de entorno:

• COMMAND_TIMEOUT: ⏱️ Tiempo máximo de ejecución en segundos (predeterminado: 30)

🛡️ Características de Seguridad

• 🔐 Aislamiento de Directorios: Los comandos solo pueden ejecutarse en directorios especificados
• 🔒 Control de Shell: Solo se permiten los shells configurados
• ⏰ Protección de Tiempo de Espera: Todos los comandos tienen un tiempo de espera configurable
• 🛑 Validación de Rutas: La validación del directorio de trabajo previene ataques de traversal
• 👤 Aislamiento de Permisos: Los comandos se ejecutan con los mismos permisos que el proceso del servidor

🛠️ Desarrollo

Configura tu entorno de desarrollo:

# 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

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Siéntete libre de:

• 🐛 Reportar errores
• 💡 Sugerir características
• 🔧 Enviar solicitudes de extracción
• 📚 Mejorar la documentación

📜 Licencia

Licencia MIT - consulta LICENSE para más detalles.