Servidor de terminales MCP

Un servidor de ejecución de terminal seguro que implementa el Protocolo de Contexto de Modelo (MCP). Este servidor proporciona capacidades de ejecución controlada de comandos con funciones de seguridad y límites de recursos.

Características

Ejecución de comandos : Ejecute comandos de shell con captura de salida y manejo de errores
Controles de seguridad : restrinja los comandos permitidos y evite la inyección de comandos
Controles de recursos :
- Tiempos de espera de comandos
- Límites de tamaño máximo de salida
Compatibilidad con el protocolo MCP :
- Formato de mensaje MCP estándar
- Anuncio de capacidad
- Compatibilidad con salida de streaming

Related MCP server: Terminal Controller for MCP

Desarrollo

Configuración local

# Clone the repository
git clone https://github.com/RinardNick/mcp-terminal.git
cd mcp-terminal

# Create and activate virtual environment using uv
uv venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

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

Publicación en PyPI

# Build the package
uv pip install build
python -m build

# Upload to PyPI
uv pip install twine
python -m twine upload dist/*

Pruebas con MCP Inspector

La herramienta MCP Inspector se puede utilizar para probar la implementación del servidor:

# Install inspector
npm install -g @modelcontextprotocol/inspector

# Test server
npx @modelcontextprotocol/inspector python3 src/mcp_terminal/server.py --allowed-commands "python,pip,git,ls,cd"

Ejecución de pruebas

# Run all tests
pytest tests/

# Run specific test file
pytest tests/test_terminal.py

# Run with coverage
pytest --cov=mcp_terminal tests/

Uso con Claude Desktop

Una vez que el paquete se publica en PyPI:

Instalar UV (si aún no está instalado):
```
pip install uv
```
Instalar el paquete usando UV :
```
uv pip install mcp-terminal
```

Configurar Claude Desktop : edite el archivo de configuración de Claude Desktop (normalmente en ~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

{
  "mcpServers": {
    "terminal": {
      "command": "uv",
      "args": [
        "pip",
        "run",
        "mcp-terminal",
        "--allowed-commands",
        "python,pip,git,ls,cd",
        "--timeout-ms",
        "30000",
        "--max-output-size",
        "1048576"
      ]
    }
  }
}

Implementación del protocolo

El servidor implementa el Protocolo de Contexto de Modelo (MCP) con las siguientes capacidades:

Anuncio de capacidades

{
  "protocol": "1.0.0",
  "name": "terminal",
  "version": "1.1.0",
  "capabilities": {
    "execute": {
      "description": "Execute a terminal command",
      "parameters": {
        "command": {
          "type": "string",
          "description": "The command to execute"
        }
      },
      "returns": {
        "type": "object",
        "properties": {
          "exitCode": { "type": "number" },
          "stdout": { "type": "string" },
          "stderr": { "type": "string" },
          "startTime": { "type": "string" },
          "endTime": { "type": "string" }
        }
      }
    }
  }
}

Formato del mensaje

Pedido :

{
  "type": "execute",
  "data": {
    "command": "echo 'hello world'"
  }
}

Respuesta :

{
  "type": "result",
  "data": {
    "command": "echo 'hello world'",
    "exitCode": 0,
    "stdout": "hello world\n",
    "stderr": "",
    "startTime": "2024-01-20T12:34:56.789Z",
    "endTime": "2024-01-20T12:34:56.790Z"
  }
}

Error :

{
  "type": "error",
  "data": {
    "message": "command not allowed"
  }
}

Consideraciones de seguridad

Validación de comandos :
- Sólo se pueden ejecutar los comandos permitidos
- Los operadores de Shell están bloqueados
- Se evitan los intentos de inyección de comandos
Protección de recursos :
- Los tiempos de espera de los comandos evitan que se cuelguen
- Los límites de tamaño de salida evitan el agotamiento de la memoria
- Manejo de errores para todos los casos de falla
Mejores prácticas :
- Establezca siempre allowed-commands en producción
- Utilice límites de tamaño y tiempo de espera conservadores
- Supervisar los registros de ejecución de comandos