Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Terminal Controller MCP Server Show me the contents of my Downloads directory"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server that enables secure terminal command execution, directory navigation, and file system operations through a standardized interface.
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
Related MCP server: Command Line Interface Enhancer
To install Terminal Controller for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @GongRzhe/terminal-controller-mcp --client claudePython 3.11+
An MCP-compatible client (such as Claude Desktop)
UV/UVX installed (optional, for UVX method)
Install the package directly from PyPI:
pip install terminal-controllerOr if you prefer to use UV:
uv pip install terminal-controllerIf you prefer to install from source:
Clone this repository:
git clone https://github.com/GongRzhe/terminal-controller-mcp.git
cd terminal-controller-mcpRun the setup script:
python setup_mcp.pyThere are two ways to configure Claude Desktop to use Terminal Controller:
Add this to your Claude Desktop configuration file:
"terminal-controller": {
"command": "uvx",
"args": ["terminal_controller"]
}"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
For Cursor, use similar configuration settings as Claude Desktop.
For other clients, refer to their documentation on how to configure external MCP servers.
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"
Terminal Controller exposes the following MCP tools:
execute_commandExecute 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_historyGet recent command execution history.
Parameters:
count: Number of recent commands to return (default: 10)
Returns:
Formatted command history record
get_current_directoryGet the current working directory.
Returns:
Path of current working directory
change_directoryChange the current working directory.
Parameters:
path: Directory path to switch to
Returns:
Operation result information
list_directoryList 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_fileWrite 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_fileRead 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_contentInsert 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_contentDelete 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_contentUpdate 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
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
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
If you encounter issues:
Check that your Python version is 3.11 or higher
Verify that your Claude Desktop configuration is correct
Try running the terminal controller directly to check for errors:
python -m terminal_controllerFor UVX-related issues, try:
uvx terminal_controllerReview your MCP client's logs for connection errors
Contributions are welcome! Please feel free to submit a Pull Request.
MIT
Change current working directory
Args:
path: Directory path to switch to
Returns:
Operation result information
Inputs: path (required).
Delete content at specific row(s) from a file
Args:
path: Path to the file
row: Row number to delete (0-based, optional)
rows: List of row numbers to delete (0-based, optional)
substring: If provided, only delete this substring within the specified row(s), not the entire row (optional)
Returns:
Operation result information
Inputs: path (required), row, rows, substring.
Execute terminal command and return results
Args:
command: Command line command to execute
timeout: Command timeout in seconds, default is 30 seconds
Returns:
Output of the command execution
Inputs: command (required), timeout.
Get recent command execution history
Args:
count: Number of recent commands to return
Returns:
Formatted command history record
Inputs: count.
Get current working directory
Returns:
Path of current working directory
Inputs: no named parameters.
Insert content at specific row(s) in a file
Args:
path: Path to the file
content: Content to insert (string or JSON object)
row: Row number to insert at (0-based, optional)
rows: List of row numbers to insert at (0-based, optional)
Returns:
Operation result information
Inputs: path (required), content (required), row, rows.
List files and subdirectories in the specified directory
Args:
path: Directory path to list contents, default is current directory
Returns:
List of directory contents
Inputs: path.
Read content from a file with optional row selection
Args:
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)
as_json: If True, attempt to parse file content as JSON (optional)
Returns:
File content or selected lines, optionally parsed as JSON
Inputs: path (required), start_row, end_row, as_json.
Update content at specific row(s) in a file
Args:
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)
substring: If provided, only replace this substring within the specified row(s), not the entire row
Returns:
Operation result information
Inputs: path (required), content (required), row, rows, +1 more.
Write content to a file
Args:
path: Path to the file
content: Content to write (string or JSON object)
mode: Write mode ('overwrite' or 'append')
Returns:
Operation result information
Inputs: path (required), content (required), mode.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 10 tools
Tools are mostly distinct: directory operations (change, get, list), command execution (execute, history), and file operations (read, write, insert, update, delete content). Overlap exists between insert, update, and delete row-based operations, but descriptions clarify differences.
All tool names follow a consistent verb_noun pattern in snake_case, e.g., change_directory, execute_command, write_file. No deviations or mixed conventions.
With 10 tools, the set is well-scoped for a terminal controller, covering directory navigation, command execution with history, and file content manipulation. Each tool serves a clear purpose without redundancy.
The set covers core terminal operations well but lacks tools for file deletion (only content deletion), directory creation, and file renaming/moving. These gaps can be worked around via execute_command, but are notable omissions.
Securely control computers you explicitly pair through files, terminals, processes, screenshots, desktop UI/input, clipboard, browser automation, diagnostics, and document tools.
Scoped, audited SSH exec, sessions, and SFTP on your saved servers without exposing credentials
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Manage remote servers, SSH terminals, files, databases and proxies with scoped access and approvals.
