CLI MCP Server

CLI MCP Server

---

Una implementación segura de un servidor de Model Context Protocol (MCP) para ejecutar operaciones controladas de línea de comandos con características de seguridad integrales.

---

Tabla de Contenidos

1. Descripción General
2. Características
3. Configuración
4. Herramientas Disponibles
   • run_command
   • show_security_rules
5. Uso con Claude Desktop
   • Configuración de Servidores en Desarrollo/No Publicados
   • Configuración de Servidores Publicados
6. Características de Seguridad
7. Manejo de Errores
8. Desarrollo
   • Requisitos Previos
   • Compilación y Publicación
   • Depuración
9. Licencia

---

Descripción General

Este servidor MCP permite la ejecución segura de comandos de línea de comandos con medidas de seguridad robustas, incluyendo listas blancas de comandos, validación de rutas y controles de ejecución. Perfecto para proporcionar acceso CLI controlado a aplicaciones LLM mientras se mantiene la seguridad.

Características

• 🔒 Ejecución segura de comandos con validación estricta
• ⚙️ Listas blancas configurables de comandos y banderas con opción 'all'
• 🛡️ Prevención y validación de recorridos de rutas
• 🚫 Protección contra inyección de operadores de shell
• ⏱️ Tiempos de espera de ejecución y límites de longitud
• 📝 Reporte detallado de errores
• 🔄 Soporte de operaciones asíncronas
• 🎯 Restricción y validación del directorio de trabajo

Configuración

Configure el servidor usando variables de entorno:

Variable	Descripción	Valor Predeterminado
ALLOWED_DIR	Directorio base para la ejecución de comandos (Requerido)	Ninguno (Requerido)
ALLOWED_COMMANDS	Lista separada por comas de comandos permitidos o 'all'	ls,cat,pwd
ALLOWED_FLAGS	Lista separada por comas de banderas permitidas o 'all'	-l,-a,--help
MAX_COMMAND_LENGTH	Longitud máxima de la cadena de comandos	1024
COMMAND_TIMEOUT	Tiempo de espera de ejecución de comandos (segundos)	30
ALLOW_SHELL_OPERATORS	Permitir operadores de shell (&&, ||, |, >, etc.)	false

Nota: Establecer ALLOWED_COMMANDS o ALLOWED_FLAGS a 'all' permitirá cualquier comando o bandera respectivamente.

Instalación

Para instalar CLI MCP Server para Claude Desktop automáticamente a través de Smithery:

npx @smithery/cli install cli-mcp-server --client claude

Herramientas Disponibles

run_command

Ejecuta comandos CLI en lista blanca dentro de directorios permitidos.

Esquema de Entrada:

{
  "command": {
    "type": "string",
    "description": "Single command to execute (e.g., 'ls -l' or 'cat file.txt')"
  }
}

Notas de Seguridad:

• Los operadores de shell (&&, |, >, >>) no son compatibles por defecto, pero pueden habilitarse con ALLOW_SHELL_OPERATORS=true
• Los comandos deben estar en la lista blanca a menos que ALLOWED_COMMANDS='all'
• Las banderas deben estar en la lista blanca a menos que ALLOWED_FLAGS='all'
• Todas las rutas se validan para estar dentro de ALLOWED_DIR

show_security_rules

Muestra la configuración de seguridad actual y las restricciones, incluyendo:

• Directorio de trabajo
• Comandos permitidos
• Banderas permitidas
• Límites de seguridad (longitud máxima de comandos y tiempo de espera)

Uso con Claude Desktop

Agregue a su ~/Library/Application\ Support/Claude/claude_desktop_config.json:

Configuración de Servidores en Desarrollo/No Publicados

{
  "mcpServers": {
    "cli-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "<path/to/the/repo>/cli-mcp-server",
        "run",
        "cli-mcp-server"
      ],
      "env": {
        "ALLOWED_DIR": "</your/desired/dir>",
        "ALLOWED_COMMANDS": "ls,cat,pwd,echo",
        "ALLOWED_FLAGS": "-l,-a,--help,--version",
        "MAX_COMMAND_LENGTH": "1024",
        "COMMAND_TIMEOUT": "30",
        "ALLOW_SHELL_OPERATORS": "false"
      }
    }
  }
}

Configuración de Servidores Publicados

{
  "mcpServers": {
    "cli-mcp-server": {
      "command": "uvx",
      "args": [
        "cli-mcp-server"
      ],
      "env": {
        "ALLOWED_DIR": "</your/desired/dir>",
        "ALLOWED_COMMANDS": "ls,cat,pwd,echo",
        "ALLOWED_FLAGS": "-l,-a,--help,--version",
        "MAX_COMMAND_LENGTH": "1024",
        "COMMAND_TIMEOUT": "30",
        "ALLOW_SHELL_OPERATORS": "false"
      }
    }
  }
}

En caso de que no funcione o no se muestre en la interfaz, limpie su caché a través de uv clean.

Características de Seguridad

• ✅ Aplicación de lista blanca de comandos con opción 'all'
• ✅ Validación de banderas con opción 'all'
• ✅ Prevención y normalización de recorridos de rutas
• ✅ Bloqueo de operadores de shell (con soporte opcional a través de ALLOW_SHELL_OPERATORS=true)
• ✅ Límites de longitud de comandos
• ✅ Tiempos de espera de ejecución
• ✅ Restricciones del directorio de trabajo
• ✅ Resolución y validación de enlaces simbólicos

Manejo de Errores

El servidor proporciona mensajes de error detallados para:

• Violaciones de seguridad (CommandSecurityError)
• Tiempos de espera de comandos (CommandTimeoutError)
• Formatos de comando inválidos
• Violaciones de seguridad de rutas
• Fallos de ejecución (CommandExecutionError)
• Errores generales de comandos (CommandError)

Desarrollo

Requisitos Previos

• Python 3.10+
• Biblioteca de protocolo MCP

Compilación y Publicación

Para preparar el paquete para distribución:

1. Sincronice las dependencias y actualice el archivo de bloqueo:

   uv sync
   

2. Compile las distribuciones del paquete:

   uv build
   

   Esto creará distribuciones de código fuente y wheel en el directorio dist/.

3. Publique en PyPI:

   uv publish --token {{YOUR_PYPI_API_TOKEN}}
   

Depuración

Dado que los servidores MCP se ejecutan a través de stdio, la depuración puede ser desafiante. Para la mejor experiencia de depuración, recomendamos encarecidamente usar el MCP Inspector.

Puede lanzar el MCP Inspector a través de npm con este comando:

npx @modelcontextprotocol/inspector uv --directory {{your source code local directory}}/cli-mcp-server run cli-mcp-server

Al lanzarlo, el Inspector mostrará una URL a la que puede acceder en su navegador para comenzar a depurar.

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulte el archivo LICENSE para más detalles.

---

Para más información o soporte, por favor abra un issue en el repositorio del proyecto.