Terminal Controller

🚀 Terminal Controller MCP Server

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

✨ Features

• Command Execution: Supports the execution of terminal commands, including file management and system operations.
• Directory Navigation: Provides directory browsing and navigation capabilities.
• File Operations: Includes operations such as file reading, writing, insertion, deletion, and updating.
• Security: Built - in security mechanisms prevent the execution of dangerous commands.

📦 Installation

System Requirements

• Operating System: Linux or macOS
• Python Version: 3.11 or higher

Installation Steps

1. Install the dependencies using the following command:

   pip install terminal_controller
   

2. Start the terminal controller server:

   python -m terminal_controller
   

📚 Client Configuration

Supported Clients

• Claude Desktop
• Other MCP - compatible clients

Configuration Example

Add the following content to the config.json file:

{
  "server_address": "localhost:8000",
  "timeout": 3600
}

💻 Usage Examples

Basic Commands

• Execute a command:

  mcp exec "ls -l"
  

• Navigate directories:

  mcp cd /path/to/directory
  

• Read a file:

  mcp read_file example.txt
  

Advanced Usage

• Insert content:

  mcp insert_file_content example.txt "new content" 5
  

• Delete content:

  mcp delete_file_content example.txt 3
  

📚 Documentation

API Reference

Command Execution

def execute_command(command: str, timeout: int = 3600) -> dict:
    """
    Execute a terminal command.
    
    Parameters:
        command (str): The command to execute.
        timeout (int): The timeout in seconds (default is 3600).
        
    Returns:
        dict: A dictionary containing the result or error information.
    """

File Reading

def read_file(path: str, start_row: int = None, end_row: int = None) -> str:
    """
    Read content from a file.
    
    Parameters:
        path (str): The file path.
        start_row (int, optional): The starting row (0 - based).
        end_row (int, optional): The ending row (0 - based, inclusive).
        
    Returns:
        str: The file content or the content within the specified range.
    """

🔧 Technical Details

Security Considerations

• Timeout Control: Prevents long - running commands.
• Blacklist of Dangerous Commands: Blocks dangerous operations such as rm -rf /.
• Error Handling: Isolates the command execution environment to ensure security.

Limitations

• By default, the server has the same file system permissions as the user running it.
• Some interactive commands may not work properly because the terminal is non - interactive.

Troubleshooting

1. Check if the Python version is 3.11 or higher.
2. Ensure that the client is configured correctly.
3. Run the terminal controller directly to check for errors:

   python -m terminal_controller
   

4. For UVX - related issues, try:

   uvx terminal_controller
   

🤝 Contribution

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

📄 License

MIT