Servidor MCP ejecutor de comandos

Un servidor de protocolo de contexto modelo para ejecutar comandos previamente aprobados de forma segura.

🎥 Demostración

https://github.com/user-attachments/assets/ed763a12-b685-4e0b-b9a5-bc948a590f51

Related MCP server: Windows Command Line MCP Server

✨ Características

• Ejecución segura de comandos con una lista de comandos previamente aprobada

• Comandos permitidos configurables a través de variables de entorno

• Desarrollado con TypeScript y MCP SDK

• Comunicación a través de stdio para una integración perfecta

• Manejo de errores y validaciones de seguridad

• Transmisión de salida de comandos en tiempo real

🚀 Instalación

Instalar dependencias:

npm install

Construir el servidor:

npm run build

Para desarrollo con reconstrucción automática:

npm run watch

⚙️ Configuración

🔒 Comandos permitidos

De forma predeterminada, se permiten los siguientes comandos:

• git

• es

• mkdir

• cd

• npm

• npx

• pitón

Puede personalizar los comandos permitidos configurando la variable de entorno ALLOWED_COMMANDS :

export ALLOWED_COMMANDS=git,ls,mkdir,python

🔌 Integración de escritorio de Claude

Para utilizar con Claude Desktop, agregue la configuración del servidor:

En MacOS:

~/Library/Application Support/Claude/claude_desktop_config.json

En Windows:

%APPDATA%/Claude/claude_desktop_config.json

Ejemplo de configuración:

{
  "mcpServers": {
    "command-executor": {
      "command": "/path/to/command-executor/build/index.js"
    }
  }
}

🛡️ Consideraciones de seguridad

El servidor ejecutor de comandos implementa varias medidas de seguridad:

1. Lista de comandos preaprobada

   • Sólo se pueden ejecutar comandos explícitamente permitidos

   • La lista predeterminada es restrictiva y se centra en la seguridad.

   • Los comandos se validan mediante prefijo para evitar la inyección.

2. Validación de comandos

   • La validación del prefijo de comando evita la inyección de comandos

   • No se ejecuta el shell para mejorar la seguridad

   • Las variables de entorno se desinfectan adecuadamente

3. Manejo de errores

   • Manejo integral de errores para comandos no autorizados

   • Borrar mensajes de error para depuración

   • Los comandos fallidos no bloquean el servidor

4. Aislamiento ambiental

   • El servidor se ejecuta en su propio entorno

   • Las variables de entorno se pueden controlar

   • Acceso limitado al sistema

💻 Desarrollo

📁 Estructura del proyecto

command-executor/
├─ src/
│  └─ index.ts      # Main server implementation
├─ build/
│  └─ index.js      # Compiled JavaScript
├─ assets/
│  └─ header.svg    # Project header image
└─ package.json     # Project configuration

🐛 Depuración

Dado que los servidores MCP se comunican a través de stdio, la depuración puede ser complicada. Recomendamos usar el Inspector MCP :

npm run inspector

El Inspector proporcionará una URL para acceder a las herramientas de depuración en su navegador.

🛠️ API de herramientas

El servidor proporciona una única herramienta:

ejecutar_comando

Ejecuta un comando previamente aprobado.

Parámetros:

• command (cadena, obligatorio): el comando a ejecutar

Ejemplo de solicitud:

{
  "name": "execute_command",
  "arguments": {
    "command": "git status"
  }
}

Ejemplo de respuesta:

{
  "content": [
    {
      "type": "text",
      "text": "On branch main\nNothing to commit, working tree clean"
    }
  ]
}

Respuesta de error:

{
  "content": [
    {
      "type": "text",
      "text": "Command execution failed: Command not allowed"
    }
  ],
  "isError": true
}

❌ Manejo de errores

El servidor proporciona mensajes de error detallados para varios escenarios:

1. Comandos no autorizados

   {
     "code": "InvalidParams",
     "message": "Command not allowed: [command]. Allowed commands: git, ls, mkdir, cd, npm, npx, python"
   }

2. Fallos de ejecución

   {
     "content": [
       {
         "type": "text",
         "text": "Command execution failed: [error message]"
       }
     ],
     "isError": true
   }

🤝 Contribuyendo

1. Bifurcar el repositorio

2. Crea tu rama de funciones

3. Confirme sus cambios

4. Empujar hacia la rama

5. Crear una nueva solicitud de extracción

📄 Licencia

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