Controlador de terminal para MCP

Un servidor de Protocolo de Contexto de Modelo (MCP) que permite la ejecución segura de comandos de terminal, navegación de directorios y operaciones del sistema de archivos a través de una interfaz estandarizada.

Características

• Ejecución de comandos : ejecute comandos de terminal con controles de tiempo de espera y captura de salida integral
• Administración de directorios : navegue y enumere el contenido del directorio con un formato intuitivo
• Medidas de seguridad : protecciones integradas contra comandos y operaciones peligrosas
• Historial de comandos : rastrea y muestra ejecuciones de comandos recientes
• Compatibilidad multiplataforma : funciona tanto en sistemas Windows como basados en UNIX
• Operaciones de archivo : leer, escribir, actualizar, insertar y eliminar contenido de archivos con precisión a nivel de fila

Instalación

Instalación mediante herrería

Para instalar Terminal Controller para Claude Desktop automáticamente a través de Smithery :

Prerrequisitos

• Python 3.11+
• Un cliente compatible con MCP (como Claude Desktop)
• UV/UVX instalado (opcional, para el método UVX)

Método 1: Instalación de PyPI (recomendado)

Instale el paquete directamente desde PyPI:

O si prefieres usar UV:

Método 2: Desde la fuente

Si prefieres instalar desde la fuente:

1. Clonar este repositorio:
   git clone https://github.com/GongRzhe/terminal-controller-mcp.git cd terminal-controller-mcp
2. Ejecute el script de configuración:
   python setup_mcp.py

Configuración del cliente

Escritorio de Claude

Hay dos formas de configurar Claude Desktop para utilizar el controlador de terminal:

Opción 1: Uso de UVX (recomendado)

Agregue esto a su archivo de configuración de Claude Desktop:

Opción 2: Usar Python directamente

La ruta de configuración varía según el sistema operativo:

• macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
• Ventanas : %APPDATA%\Claude\claude_desktop_config.json

Cursor

Para el cursor, utilice configuraciones similares a las de Claude Desktop.

Otros clientes de MCP

Para otros clientes, consulte su documentación sobre cómo configurar servidores MCP externos.

Uso

Una vez configurado, podrás utilizar lenguaje natural para interactuar con tu terminal a través de tu cliente MCP:

• "Ejecute el comando ls -la en el directorio actual"
• "Ir a mi carpeta Documentos"
• "Muéstrame el contenido de mi directorio de Descargas"
• "Muéstrame mi historial de comandos reciente"
• "Leer el contenido de config.json"
• "Actualizar la línea 5 en mi archivo script.py con 'print("Hola Mundo")'"
• "Eliminar las líneas 10-15 del archivo de registro"
• "Insertar una nueva línea al principio de mi archivo de texto"

Referencia de API

Terminal Controller expone las siguientes herramientas MCP:

execute_command

Ejecutar un comando de terminal y devolver sus resultados.

Parámetros:

• command : El comando de línea de comandos a ejecutar
• timeout : Tiempo de espera del comando en segundos (predeterminado: 30)

Devoluciones:

• Salida de la ejecución del comando, incluyendo stdout, stderr y estado de ejecución

get_command_history

Obtener el historial reciente de ejecución de comandos.

Parámetros:

• count : Número de comandos recientes a devolver (predeterminado: 10)

Devoluciones:

• Registro de historial de comandos formateado

get_current_directory

Obtener el directorio de trabajo actual.

Devoluciones:

• Ruta del directorio de trabajo actual

change_directory

Cambiar el directorio de trabajo actual.

Parámetros:

• path : Ruta del directorio al que cambiar

Devoluciones:

• Información del resultado de la operación

list_directory

Enumerar archivos y subdirectorios en el directorio especificado.

Parámetros:

• path : Ruta del directorio para listar contenidos (predeterminado: directorio actual)

Devoluciones:

• Lista de contenidos del directorio, formateada con iconos para directorios y archivos

write_file

Escribe contenido en un archivo con opciones de sobrescribir o agregar.

Parámetros:

• path : Ruta al archivo
• content : Contenido para escribir
• mode : modo de escritura ('sobrescribir' o 'agregar', predeterminado: 'sobrescribir')

Devoluciones:

• Información del resultado de la operación, incluida la verificación de escritura exitosa

read_file

Leer el contenido de un archivo con selección de filas opcional.

Parámetros:

• path : Ruta al archivo
• start_row : Fila inicial desde la que leer (basada en 0, opcional)
• end_row : Fila final a leer (basada en 0, inclusive, opcional)

Devoluciones:

• Contenido del archivo o líneas seleccionadas

insert_file_content

Insertar contenido en filas específicas de un archivo.

Parámetros:

• path : Ruta al archivo
• content : Contenido a insertar
• row : Número de fila a insertar (basado en 0, opcional)
• rows : Lista de números de fila para insertar (basado en 0, opcional)

Devoluciones:

• Información del resultado de la operación

delete_file_content

Eliminar contenido en filas específicas de un archivo.

Parámetros:

• path : Ruta al archivo
• row : Número de fila a eliminar (basado en 0, opcional)
• rows : Lista de números de fila para eliminar (basados en 0, opcional)

Devoluciones:

• Información del resultado de la operación

update_file_content

Actualizar el contenido en filas específicas de un archivo.

Parámetros:

• path : Ruta al archivo
• content : Nuevo contenido para colocar en las filas especificadas
• row : Número de fila a actualizar (basado en 0, opcional)
• rows : Lista de números de fila para actualizar (basado en 0, opcional)

Devoluciones:

• Información del resultado de la operación

Consideraciones de seguridad

Terminal Controller implementa varias medidas de seguridad:

• Controles de tiempo de espera para evitar comandos de ejecución prolongada
• Lista negra de comandos peligrosos (rm -rf /, format, mkfs)
• Manejo adecuado de errores y aislamiento de la ejecución de comandos
• Acceso únicamente a los comandos y directorios específicamente concedidos

Limitaciones

• Sólo los comandos que se completen dentro del período de tiempo de espera devolverán resultados
• De forma predeterminada, el servidor tiene acceso a los mismos permisos del sistema de archivos que el usuario que lo ejecuta.
• Es posible que algunos comandos interactivos no funcionen como se espera debido a la naturaleza no interactiva de la interfaz del terminal.

Solución de problemas

Si encuentra problemas:

1. Comprueba que tu versión de Python sea 3.11 o superior
2. Verifique que su configuración de Claude Desktop sea correcta
3. Intente ejecutar el controlador de terminal directamente para verificar si hay errores:
   python -m terminal_controller
4. Para problemas relacionados con UVX, pruebe:
   uvx terminal_controller
5. Revise los registros de su cliente MCP para detectar errores de conexión

Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.

Licencia

Instituto Tecnológico de Massachusetts (MIT)