Terminal Controller

by gongrzhe

33 stars

Not rated

GitHub

About

Enables secure terminal command execution, directory navigation, and file system operations across Windows and UNIX-based systems, with built-in security measures to prevent dangerous operations.

Details

Author: gongrzhe
Repository: GongRzhe/terminal-controller-mcp
GitHub stars: 33
License: MIT License
Categories: Productivity, AI, Design, File Management, Infrastructure, Developer Tools, Frontend
Tags: #integration

- 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

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below
Plugin Name Terminal Controller

Command (node, npx, python, etc.) uvx
Arguments
- Argument 1 terminal_controller
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "terminal controller": {
            "cwd": null,
            "env": {},
            "args": [
                "terminal_controller"
            ],
            "shell": false,
            "command": "uvx"
        }
    }
}

JSON

{
    "mcpServers": {
        "terminal controller": {
            "cwd": null,
            "env": {},
            "args": [
                "/c",
                "uvx",
                "terminal_controller"
            ],
            "shell": false,
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "terminal controller": {
            "cwd": null,
            "env": {},
            "args": [
                "terminal_controller"
            ],
            "shell": false,
            "command": "uvx"
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "terminal controller": {
            "cwd": null,
            "env": {},
            "args": [
                "terminal_controller"
            ],
            "shell": false,
            "command": "uvx"
        }
    }
}

JSON

{
    "mcpServers": {
        "terminal controller": {
            "cwd": null,
            "env": {},
            "args": [
                "/c",
                "uvx",
                "terminal_controller"
            ],
            "shell": false,
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "terminal controller": {
            "cwd": null,
            "env": {},
            "args": [
                "terminal_controller"
            ],
            "shell": false,
            "command": "uvx"
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "terminal controller": {
            "cwd": null,
            "env": {},
            "args": [
                "terminal_controller"
            ],
            "shell": false,
            "command": "uvx"
        }
    }
}

JSON

{
    "mcpServers": {
        "terminal controller": {
            "cwd": null,
            "env": {},
            "args": [
                "/c",
                "uvx",
                "terminal_controller"
            ],
            "shell": false,
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "terminal controller": {
            "cwd": null,
            "env": {},
            "args": [
                "terminal_controller"
            ],
            "shell": false,
            "command": "uvx"
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "terminal controller": {
            "cwd": null,
            "env": {},
            "args": [
                "terminal_controller"
            ],
            "shell": false,
            "command": "uvx"
        }
    }
}

JSON

{
    "mcpServers": {
        "terminal controller": {
            "cwd": null,
            "env": {},
            "args": [
                "/c",
                "uvx",
                "terminal_controller"
            ],
            "shell": false,
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "terminal controller": {
            "cwd": null,
            "env": {},
            "args": [
                "terminal_controller"
            ],
            "shell": false,
            "command": "uvx"
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "terminal controller": {
            "cwd": null,
            "env": {},
            "args": [
                "terminal_controller"
            ],
            "shell": false,
            "command": "uvx"
        }
    }
}

JSON

{
    "mcpServers": {
        "terminal controller": {
            "cwd": null,
            "env": {},
            "args": [
                "/c",
                "uvx",
                "terminal_controller"
            ],
            "shell": false,
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "terminal controller": {
            "cwd": null,
            "env": {},
            "args": [
                "terminal_controller"
            ],
            "shell": false,
            "command": "uvx"
        }
    }
}

From the repository

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

- "Run the command ls -la in the current directory"
- "Navigate to my Documents folder"
- "Show me the contents of my Downloads directory"
- "Show me my recent command history"
- "Read the content of config.json"
- "Update line 5 in my script.py file with 'print(\"Hello World\")'"
- "Delete lines 10-15 from the log file"
- "Insert a new line at the beginning of my text file"

To install Terminal Controller for Claude Desktop automatically via Smithery:

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

Install the package directly from PyPI:

pip install terminal-controller

Or if you prefer to use UV:

uv pip install terminal-controller

`execute_command`

Execute a terminal command and return its results. Parameters: command (string), timeout (int, default: 30)

`get_command_history`

Get recent command execution history. Parameters: count (int, default: 10)

`get_current_directory`

Get the current working directory.

`change_directory`

Change the current working directory. Parameters: path (string)

`list_directory`

List files and subdirectories in the specified directory. Parameters: path (string, default: current directory)

`write_file`

Write content to a file with overwrite or append options. Parameters: path (string), content (string), mode (string, default: 'overwrite')

`read_file`

Read content from a file with optional row selection. Parameters: path (string), start_row (int, optional), end_row (int, optional)

`insert_file_content`

Insert content at specific row(s) in a file. Parameters: path (string), content (string), row (int, optional), rows (list of int, optional)

`delete_file_content`

Delete content at specific row(s) from a file. Parameters: path (string), row (int, optional), rows (list of int, optional)

`update_file_content`

Update content at specific row(s) in a file. Parameters: path (string), content (string), row (int, optional), rows (list of int, optional)

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "terminal controller": {
            "cwd": null,
            "env": {},
            "args": [
                "terminal_controller"
            ],
            "shell": false,
            "command": "uvx"
        }
    }
}

Linux

{
    "cwd": null,
    "env": [],
    "args": [
        "terminal_controller"
    ],
    "shell": false,
    "command": "uvx"
}

Macos

{
    "cwd": null,
    "env": [],
    "args": [
        "terminal_controller"
    ],
    "shell": false,
    "command": "uvx"
}

Windows

{
    "cwd": null,
    "env": [],
    "args": [
        "/c",
        "uvx",
        "terminal_controller"
    ],
    "shell": false,
    "command": "cmd"
}

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.

![](https://badge.mcpx.dev?type=server 'MCP Server')

Features

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:

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 of the command execution, 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 (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
- By default, the server has access to the same file system permissions as the user running it
- Some interactive commands may not work as expected due to the non-interactive nature of the terminal interface

Troubleshooting

If you encounter issues:

1. Check that your Python version is 3.11 or higher
2. Verify that your Claude Desktop configuration is correct
3. Try running the terminal controller directly to check for errors:

   python -m terminal_controller

4. For UVX-related issues, try:

   uvx terminal_controller

5. Review your MCP client's logs for connection errors

Contributing

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

License

MIT

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

execute_command

get_command_history

get_current_directory

change_directory

list_directory

write_file

read_file

insert_file_content

delete_file_content

update_file_content

Claude Desktop / Cursor

Linux

Macos

Windows

Terminal Controller for MCP

Features

Installation

Installing via Smithery

Prerequisites

Method 1: PyPI Installation (Recommended)

Method 2: From Source

Client Configuration

Claude Desktop

Option 1: Using UVX (Recommended)

Option 2: Using Python Directly

Cursor

Other MCP Clients

Usage

API Reference

execute_command

get_command_history

get_current_directory

change_directory

list_directory

write_file

read_file

insert_file_content

delete_file_content

update_file_content

Security Considerations

Limitations

Troubleshooting

Contributing

License

Install

More like this

Time

Context 7

1Panel

🔎 GPT Researcher

Serena

FastMCP v2 🚀

`execute_command`

`get_command_history`

`get_current_directory`

`change_directory`

`list_directory`

`write_file`

`read_file`

`insert_file_content`

`delete_file_content`

`update_file_content`

`execute_command`

`get_command_history`

`get_current_directory`

`change_directory`

`list_directory`

`write_file`

`read_file`

`insert_file_content`

`delete_file_content`

`update_file_content`