https://github.com/gongrzhe/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.
https://github.com/gongrzhe/terminal-controller-mcp
Last synced: 3 months ago
JSON representation
A Model Context Protocol (MCP) server that enables secure terminal command execution, directory navigation, and file system operations through a standardized interface.
- Host: GitHub
- URL: https://github.com/gongrzhe/terminal-controller-mcp
- Owner: GongRzhe
- License: mit
- Created: 2025-02-25T16:18:55.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-04-15T16:45:42.000Z (6 months ago)
- Last Synced: 2025-06-10T11:58:56.378Z (4 months ago)
- Language: Python
- Homepage:
- Size: 43 KB
- Stars: 54
- Watchers: 1
- Forks: 12
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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