# terminal-controller-mcp

> MCP Server

This repository provides a Model Context Protocol (MCP) server, enabling secure terminal command execution, directory navigation, and file system operations through a standardized interface. It supports cross-platform functionality and offers security measures.

## Overview

- **Category:** System Tools
- **Language:** Python
- **Stars:** 99
- **Forks:** 2
- **Owner:** GongRzhe
- **GitHub:** https://github.com/GongRzhe/terminal-controller-mcp
- **Created:** 2025-02-25T16:18:55+00:00
- **Updated:** 2025-03-28T23:34:27+00:00
- **Source:** https://model-context-protocol.com/servers/secure-terminal-command-file-system-server

## Setup

## Setup

### 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.

## Tools

## Available Tools

		1. Command Execution (Run terminal commands with timeout controls and comprehensive output capture)
		2. Directory Management (Navigate and list directory contents with intuitive formatting)
		3. Security Measures (Built-in safeguards against dangerous commands and operations)
		4. Command History (Track and display recent command executions)
		5. Cross-Platform Support (Works on both Windows and UNIX-based systems)
		6. `execute_command` (Execute a terminal command and return its results.)
		7. `get_command_history` (Get recent command execution history.)
		8. `get_current_directory` (Get the current working directory.)
		9. `change_directory` (Change the current working directory.)
		10. `list_directory` (List files and subdirectories in the specified directory.)