terminal-controller-mcp
A Model Context Protocol (MCP) server that enables secure terminal command execution, directory navigation, and file system operations through a standardized interface.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/gongrzhe--terminal-controller-mcp)HTML
<a href="/listings/gongrzhe--terminal-controller-mcp"><img src="/api/listings/gongrzhe--terminal-controller-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Installing via Smithery
To install Terminal Controller for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@GongRzhe/terminal-controller-mcp):
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
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 264 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 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://smithery.ai/server/@GongRzhe/terminal-controller-mcp)
- ## 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](https://smithery.ai/server/@GongRzhe/terminal-controller-mcp):
- ```bash
- 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:
- ```bash
- pip install terminal-controller
- ```
- Or if you prefer to use UV:
- ```bash
- uv pip install terminal-controller
- ```
- ### Method 2: From Source
- If you prefer to install from source:
- 1. Clone this repository:
- ```bash
- git clone https://github.com/GongRzhe/terminal-controller-mcp.git
- cd terminal-controller-mcp
- ```
- 2. Run the setup script:
- ```bash
- 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:
- ```json
- "terminal-controller": {
- "command": "uvx",
- "args": ["terminal_controller"]
- }
- ```
- #### Option 2: Using Python Directly
- ```json
- "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:
- - "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"
- ## 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:
- ```bash
- python -m terminal_controller
- ```
- 4. For UVX-related issues, try:
- ```bash
- 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
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.