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.

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:

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:

• "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

... View full README on GitHub