Skip to main content
Glama
Terminal Controller for MCP

Terminal Controller for MCP

by GongRzhe

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

Related MCP server: MCP Server

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)

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:

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

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

Security Considerations

Terminal Controller implements several security measures:

  • Timeout controls to prevent long-running commands

  • Blacklisting of dangerous commands (rm -rf /, format, mkfs)

  • Proper error handling and isolation of command execution

  • Access only to the commands and directories specifically granted

Limitations

  • Only commands that complete within the timeout period will return results

  • By default, the server has access to the same file system permissions as the user running it

  • Some interactive commands may not work as expected due to the non-interactive nature of the terminal interface

Troubleshooting

If you encounter issues:

  1. Check that your Python version is 3.11 or higher

  2. Verify that your Claude Desktop configuration is correct

  3. Try running the terminal controller directly to check for errors:

    python -m terminal_controller
  4. For UVX-related issues, try:

    uvx terminal_controller
  5. Review your MCP client's logs for connection errors

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Available Tools

10 tools
change_directoryC
Change current working directory

Args:
    path: Directory path to switch to

Returns:
    Operation result information

Inputs: path (required).

delete_file_contentA
Delete content at specific row(s) from a file

Args:
    path: Path to the file
    row: Row number to delete (0-based, optional)
    rows: List of row numbers to delete (0-based, optional)
    substring: If provided, only delete this substring within the specified row(s), not the entire row (optional)

Returns:
    Operation result information

Inputs: path (required), row, rows, substring.

execute_commandB
Execute terminal command and return results

Args:
    command: Command line command to execute
    timeout: Command timeout in seconds, default is 30 seconds

Returns:
    Output of the command execution

Inputs: command (required), timeout.

get_command_historyB
Get recent command execution history

Args:
    count: Number of recent commands to return

Returns:
    Formatted command history record

Inputs: count.

get_current_directoryA
Get current working directory

Returns:
    Path of current working directory

Inputs: no named parameters.

insert_file_contentB
Insert content at specific row(s) in a file

Args:
    path: Path to the file
    content: Content to insert (string or JSON object)
    row: Row number to insert at (0-based, optional)
    rows: List of row numbers to insert at (0-based, optional)

Returns:
    Operation result information

Inputs: path (required), content (required), row, rows.

list_directoryA
List files and subdirectories in the specified directory

Args:
    path: Directory path to list contents, default is current directory

Returns:
    List of directory contents

Inputs: path.

read_fileA
Read content from a file with optional row selection

Args:
    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)
    as_json: If True, attempt to parse file content as JSON (optional)

Returns:
    File content or selected lines, optionally parsed as JSON

Inputs: path (required), start_row, end_row, as_json.

update_file_contentA
Update content at specific row(s) in a file

Args:
    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)
    substring: If provided, only replace this substring within the specified row(s), not the entire row

Returns:
    Operation result information

Inputs: path (required), content (required), row, rows, +1 more.

write_fileB
Write content to a file

Args:
    path: Path to the file
    content: Content to write (string or JSON object)
    mode: Write mode ('overwrite' or 'append')

Returns:
    Operation result information

Inputs: path (required), content (required), mode.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: directory change/get/list, file read/write/insert/update/delete, command execution, and history retrieval. No overlapping functionality.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern in snake_case, using imperative verbs like change, delete, execute, get, insert, list, read, update, write. The naming is predictable and uniform.

    Tool Count5/5

    With 10 tools, the set is well-scoped for a terminal controller, providing essential file and directory operations plus command execution without oversaturation.

    Completeness4/5

    The surface covers core file CRUD (create via write, read, update, delete) and directory navigation, plus command execution and history. Missing directory creation/deletion and file copy/move, but these are minor gaps for typical agent workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server allowing LLMs to execute commands on Windows terminals, including local shells (cmd, PowerShell, bash) and remote SSH connections with a 3-level security model.
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      A secure MCP server for shell operations, terminal management, and process control, enabling AI assistants to safely execute commands and manage interactive sessions.
      13
      158 npm
      6
      MIT