local-only server

The server can only run on the client’s local machine because it depends on local resources.

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

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

Contribuyendo

Bifurcar el repositorio
Crea tu rama de funciones ( git checkout -b feature/amazing-feature )
Confirme sus cambios ( git commit -m 'Add some amazing feature' )
Empujar a la rama ( git push origin feature/amazing-feature )
Abrir una solicitud de extracción

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

You must be authenticated.

A

security – no known vulnerabilities

A

license - permissive license

A

quality - confirmed to work

Tools

run_command

Un servidor de ejecución de terminal seguro que permite la ejecución controlada de comandos con funciones de seguridad y límites de recursos a través del Protocolo de Contexto de Modelo (MCP).

Related Resources

Reddit Discussion about this server

MCP Terminal Server