Terminal Controller MCP Server

Overview

Terminal Controller is an MCP server that provides a secure interface for terminal operations. It allows AI assistants to execute commands, navigate directories, and perform file operations on your behalf through natural language instructions.

Installation

Prerequisites

• Python 3.11 or higher
• An MCP-compatible client (Claude Desktop, Cursor, etc.)
• UV/UVX (optional, for the recommended installation method)

Installation Methods

Method 1: PyPI Installation (Recommended)

Install directly from PyPI using pip:

pip install terminal-controller

Or using UV:

uv pip install terminal-controller

Method 2: From Source

If you prefer installing from source:

1. Clone the repository:

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

2. Run the setup script:

python setup_mcp.py

Automated Installation via Smithery

For Claude Desktop users, you can use Smithery for automatic installation:

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

Client Configuration

Claude Desktop

Configure Claude Desktop by editing its configuration file:

Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Option 1: Using UVX (Recommended)

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

Option 2: Using Python Directly

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

Cursor and Other MCP Clients

Use similar configuration settings as Claude Desktop, adjusting according to the client's specific requirements.

Usage Examples

Once configured, you can use natural language to interact with your terminal:

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

Security Considerations

Terminal Controller includes built-in safeguards against potentially dangerous commands. However, as with any tool that can execute commands on your system, you should be cautious about the instructions you give to the AI assistant.

Troubleshooting

If you encounter issues:

1. Ensure Python 3.11+ is installed and in your PATH
2. Verify your client configuration is correct
3. Check that the terminal-controller package is properly installed
4. Look for error messages in your client's logs