An MCP server that provides secure terminal command execution, directory navigation, and file system operations through a standardized interface with built-in security measures and cross-platform support.

Installation

Smithery

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

PyPI

pip install terminal-controller

UV

uv pip install terminal-controller

From Source

git clone https://github.com/GongRzhe/terminal-controller-mcp.git
cd terminal-controller-mcp
python setup_mcp.py

Configuration

Claude Desktop (UVX)

"terminal-controller": {
  "command": "uvx",
  "args": ["terminal_controller"]
}

Claude Desktop (Python)

"terminal-controller": {
  "command": "python",
  "args": ["-m", "terminal_controller"]
}

Available Tools

Tool	Description
execute_command	Executes a terminal command and returns results with timeout control
get_command_history	Retrieves the history of recently executed commands
get_current_directory	Gets the current working directory
change_directory	Changes the current working directory
list_directory	Lists files and subdirectories in the specified directory
write_file	Writes content to a file with overwrite or append options
read_file	Reads file content with optional line selection
insert_file_content	Inserts content at specified line(s) in a file
delete_file_content	Deletes content from specified line(s) in a file
update_file_content	Updates content at specified line(s) in a file

Features

• Command execution with timeout control and comprehensive output capture
• Directory management with navigation and listing capabilities
• Security measures with built-in protections against dangerous commands
• Command history tracking and recent execution display
• Cross-platform support for Windows and UNIX systems
• File operations with line-level precision for read, write, update, insert, and delete capabilities

Usage Examples

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

Notes

Requires Python 3.11+ and implements security measures including timeout control, dangerous command blacklisting, and proper error handling. Configuration paths vary by OS: macOS (~/.../Claude/claude_desktop_config.json) and Windows (%APPDATA%\Claude\claude_desktop_config.json).