Terminal Controller for MCP
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
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 claudePrerrequisitos
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-controllerO si prefieres usar UV:
uv pip install terminal-controllerMétodo 2: Desde la fuente
Si prefieres instalar desde la fuente:
Clonar este repositorio:
git clone https://github.com/GongRzhe/terminal-controller-mcp.git cd terminal-controller-mcpEjecute 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.jsonVentanas :
%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 -laen 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 ejecutartimeout: 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 archivocontent: Contenido para escribirmode: 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 archivostart_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 archivocontent: Contenido a insertarrow: 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 archivorow: 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 archivocontent: Nuevo contenido para colocar en las filas especificadasrow: 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:
Comprueba que tu versión de Python sea 3.11 o superior
Verifique que su configuración de Claude Desktop sea correcta
Intente ejecutar el controlador de terminal directamente para verificar si hay errores:
python -m terminal_controllerPara problemas relacionados con UVX, pruebe:
uvx terminal_controllerRevise 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 toolschange_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
Scored across 10 tools
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.
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.
With 10 tools, the set is well-scoped for a terminal controller, providing essential file and directory operations plus command execution without oversaturation.
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
Related MCP Connectors
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
The Remote MCP server acts as a standardized bridge between LLM applications (like Claude, ChatGPT, and Cursor) and external services, enabling AI agents to access external tools and resources. Its primary capability is providing a centralized search tool to discover other MCP servers and their respective tools. Unlike local implementations, it runs remotely with OAuth authentication and permission controls for security.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP 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
- AlicenseNot gradedqualityDmaintenanceA modular MCP server providing file operations, web search, URL scraping, and sandboxed command execution for LLM interactions.1MIT
- AlicenseBqualityCmaintenanceA secure MCP server for shell operations, terminal management, and process control, enabling AI assistants to safely execute commands and manage interactive sessions.13158 npm6MIT
- AlicenseNot gradedqualityBmaintenanceA local MCP server that enables LLMs to execute shell commands on remote hosts over SSH with multiple authentication methods.3MIT