Skip to main content
Glama
Terminal Controller for MCP

Terminal Controller for MCP

by GongRzhe

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.

insignia de herrería

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

Related MCP server: MCP Server

Instalación

Instalación mediante herrería

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

npx -y @smithery/cli install @GongRzhe/terminal-controller-mcp --client claude

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:

pip install terminal-controller

O si prefieres usar UV:

uv pip install terminal-controller

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:

"terminal-controller": {
  "command": "uvx",
  "args": ["terminal_controller"]
}

Opción 2: Usar Python directamente

"terminal-controller": {
  "command": "python",
  "args": ["-m", "terminal_controller"]
}

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)

Available Tools

10 tools
change_directoryC
Change current working directory

Args:
    path: Directory path to switch to

Returns:
    Operation result information

Inputs: path (required).

delete_file_contentA
Delete content at specific row(s) from a file

Args:
    path: Path to the file
    row: Row number to delete (0-based, optional)
    rows: List of row numbers to delete (0-based, optional)
    substring: If provided, only delete this substring within the specified row(s), not the entire row (optional)

Returns:
    Operation result information

Inputs: path (required), row, rows, substring.

execute_commandB
Execute terminal command and return results

Args:
    command: Command line command to execute
    timeout: Command timeout in seconds, default is 30 seconds

Returns:
    Output of the command execution

Inputs: command (required), timeout.

get_command_historyB
Get recent command execution history

Args:
    count: Number of recent commands to return

Returns:
    Formatted command history record

Inputs: count.

get_current_directoryA
Get current working directory

Returns:
    Path of current working directory

Inputs: no named parameters.

insert_file_contentB
Insert content at specific row(s) in a file

Args:
    path: Path to the file
    content: Content to insert (string or JSON object)
    row: Row number to insert at (0-based, optional)
    rows: List of row numbers to insert at (0-based, optional)

Returns:
    Operation result information

Inputs: path (required), content (required), row, rows.

list_directoryA
List files and subdirectories in the specified directory

Args:
    path: Directory path to list contents, default is current directory

Returns:
    List of directory contents

Inputs: path.

read_fileA
Read content from a file with optional row selection

Args:
    path: Path to the file
    start_row: Starting row to read from (0-based, optional)
    end_row: Ending row to read to (0-based, inclusive, optional)
    as_json: If True, attempt to parse file content as JSON (optional)

Returns:
    File content or selected lines, optionally parsed as JSON

Inputs: path (required), start_row, end_row, as_json.

update_file_contentA
Update content at specific row(s) in a file

Args:
    path: Path to the file
    content: New content to place at the specified row(s)
    row: Row number to update (0-based, optional)
    rows: List of row numbers to update (0-based, optional)
    substring: If provided, only replace this substring within the specified row(s), not the entire row

Returns:
    Operation result information

Inputs: path (required), content (required), row, rows, +1 more.

write_fileB
Write content to a file

Args:
    path: Path to the file
    content: Content to write (string or JSON object)
    mode: Write mode ('overwrite' or 'append')

Returns:
    Operation result information

Inputs: path (required), content (required), mode.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: directory change/get/list, file read/write/insert/update/delete, command execution, and history retrieval. No overlapping functionality.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern in snake_case, using imperative verbs like change, delete, execute, get, insert, list, read, update, write. The naming is predictable and uniform.

    Tool Count5/5

    With 10 tools, the set is well-scoped for a terminal controller, providing essential file and directory operations plus command execution without oversaturation.

    Completeness4/5

    The surface covers core file CRUD (create via write, read, update, delete) and directory navigation, plus command execution and history. Missing directory creation/deletion and file copy/move, but these are minor gaps for typical agent workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server allowing LLMs to execute commands on Windows terminals, including local shells (cmd, PowerShell, bash) and remote SSH connections with a 3-level security model.
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      A secure MCP server for shell operations, terminal management, and process control, enabling AI assistants to safely execute commands and manage interactive sessions.
      13
      158 npm
      6
      MIT