MCP HubMCP Hub
GongRzhe

terminal-controller-mcp

by: GongRzhe

A Model Context Protocol (MCP) server that enables secure terminal command execution, directory navigation, and file system operations through a standardized interface.

24created 25/02/2025
Visit
Protocol
Terminal

📌Overview

Purpose: The Terminal Controller for MCP serves to facilitate secure execution of terminal commands, directory navigation, and file system operations through a standardized interface.

Overview: This framework provides a robust Model Context Protocol (MCP) server that allows users to execute commands securely in a cross-platform environment. The system harnesses built-in security measures to enhance user safety while enabling seamless interaction with terminal functionalities.

Key Features:

  • Command Execution: Allows users to run terminal commands with control over execution time, ensuring comprehensive output capture for effective command management.

  • Directory Management: Facilitates easy navigation and listing of directory contents with intuitive formatting, improving user experience during file operations.

  • Security Measures: Incorporates safeguards against executing dangerous commands and operations, protecting users from potentially harmful actions.

  • Command History: Tracks and displays a list of recent command executions, enhancing user awareness and accessibility to previously run commands.

  • Cross-Platform Support: Compatible with both Windows and UNIX-based systems, providing flexibility and broad usability for diverse environments.

Terminal Controller for MCP

A Model Context Protocol (MCP) server that enables secure terminal command execution, directory navigation, and file system operations through a standardized interface.

Features

  • Command Execution: Run terminal commands with timeout controls and comprehensive output capture
  • Directory Management: Navigate and list directory contents with intuitive formatting
  • Security Measures: Built-in safeguards against dangerous commands and operations
  • Command History: Track and display recent command executions
  • Cross-Platform Support: Works on both Windows and UNIX-based systems
  • File Operations: Read, write, update, insert, and delete file content with row-level precision

Installation

Installing via Smithery

To install Terminal Controller for Claude Desktop automatically via Smithery:

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

Prerequisites

  • Python 3.11+
  • An MCP-compatible client (such as Claude Desktop)
  • UV/UVX installed (optional, for UVX method)

Method 1: PyPI Installation (Recommended)

Install the package directly from PyPI:

pip install terminal-controller

Or if you prefer to use UV:

uv pip install terminal-controller

Method 2: From Source

If you prefer to install from source:

  1. Clone this repository:

    git clone https://github.com/GongRzhe/terminal-controller-mcp.git
cd terminal-controller-mcp

  2. Run the setup script:

    python setup_mcp.py

Client Configuration

Claude Desktop

There are two ways to configure Claude Desktop to use Terminal Controller:

Option 1: Using UVX (Recommended)

Add this to your Claude Desktop configuration file:

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

Option 2: Using Python Directly

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

The configuration path varies by operating system:

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

Cursor

For Cursor, use similar configuration settings as Claude Desktop.

Other MCP Clients

For other clients, refer to their documentation on how to configure external MCP servers.

Usage

Once configured, you can use natural language to interact with your terminal through your MCP client, such as:

  • Run terminal commands (e.g., ls -la)
  • Navigate directories
  • Show directory contents
  • Display recent command history
  • Read, update, delete, or insert content in files at specific lines

API Reference

Terminal Controller exposes the following MCP tools:

execute_command

Execute a terminal command and return its results.

Parameters:

  • command: The command line command to execute
  • timeout: Command timeout in seconds (default: 30)

Returns:

  • Output including stdout, stderr, and execution status

get_command_history

Get recent command execution history.

Parameters:

  • count: Number of recent commands to return (default: 10)

Returns:

  • Formatted command history record

get_current_directory

Get the current working directory.

Returns:

  • Path of current working directory

change_directory

Change the current working directory.

Parameters:

  • path: Directory path to switch to

Returns:

  • Operation result information

list_directory

List files and subdirectories in the specified directory.

Parameters:

  • path: Directory path to list contents (default: current directory)

Returns:

  • List of directory contents, formatted with icons for directories and files

write_file

Write content to a file with overwrite or append options.

Parameters:

  • path: Path to the file
  • content: Content to write
  • mode: Write mode ('overwrite' or 'append', default: 'overwrite')

Returns:

  • Operation result information including verification of successful write

read_file

Read content from a file with optional row selection.

Parameters:

  • 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)

Returns:

  • File content or selected lines

insert_file_content

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

Parameters:

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

Returns:

  • Operation result information

delete_file_content

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

Parameters:

  • path: Path to the file
  • row: Row number to delete (0-based, optional)
  • rows: List of row numbers to delete (0-based, optional)

Returns:

  • Operation result information

update_file_content

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

Parameters:

  • 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)

Returns:

  • Operation result information

Security Considerations

Terminal Controller implements several security measures:

  • Timeout controls to prevent long-running commands
  • Blacklisting of dangerous commands like rm -rf /, format, mkfs
  • Proper error handling and isolation of command execution
  • Access only to the commands and directories specifically granted

Limitations

  • Only commands that complete within the timeout period will return results
  • Server access permissions are limited to the user running it
  • Some interactive commands may not work as expected due to the non-interactive interface

Troubleshooting

If you encounter issues:

  1. Verify Python 3.11+ is installed
  2. Check Claude Desktop configuration for correctness
  3. Run the terminal controller directly to check for errors: 
    python -m terminal_controller
  4. For UVX-related issues, try: 
    uvx terminal_controller
  5. Review MCP client logs for connection errors

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT