Terminal Controller MCP server for AI agents

Terminal Controller for MCP is a secure server that enables terminal command execution, directory navigation, and file system operations through a standardized interface, supporting both Windows and UNIX-based systems with built-in security features.

Installation

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 using UV:

uv pip install terminal-controller

Method 2: From Source

Clone the repository:

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

Run the setup script:
```
python setup_mcp.py
```

Client Configuration

Claude Desktop

Configure Claude Desktop to use Terminal Controller in one of two ways:

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"]
}

Configuration file locations:

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:

"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

`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

`list_directory`

List 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_file`

Write 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_file`

Read 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_content`

Insert 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_content`

Delete 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_content`

Update 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

Troubleshooting

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_controller
```
For UVX-related issues, try:
```
uvx terminal_controller
```
Review your MCP client's logs for connection errors

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "terminal-controller" '{"command":"python","args":["-m","terminal_controller"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect