terminal-controller

Terminal Controller for MCP exposes a secure, scriptable interface to perform terminal operations via MCP clients. You can execute commands, navigate and inspect directories, read and modify files, and inspect or update command history through the provided MCP tools. This enables you to integrate shell capabilities into your MCP conversations, while applying the server's built-in safeguards such as command timeouts and blacklists to prevent potentially dangerous actions. Typical use cases include running non-interactive shell commands, listing and reading files, and updating configuration or script files directly from your MCP client.

Prerequisites:

• Python 3.11 or newer
• An MCP-compatible client (e.g., Claude Desktop) or any MCP client that can configure external MCP servers
• Optional: UV/UVX for alternative setup paths

Method 1: PyPI Installation (Recommended)

1. Install the package from PyPI:

pip install terminal-controller

2. Run the MCP server:

python -m terminal_controller

Method 2: From Source

1. Clone the repository and install dependencies:

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

2. Run the setup script or start the server directly:

python setup_mcp.py

3. Start the MCP server (alternative):

python -m terminal_controller

Method 3: UV/UVX (optional)

1. If you prefer UV/UVX, install and run via UVX:

uvx terminal_controller

2. Or run via UV directly if your environment uses UV/uvm:

uv pip install terminal-controller
uvm -m terminal_controller

Notes:

• The server is designed to operate with the same permissions as the user running it. Exercise caution in production environments.
• By default, commands have a timeout to prevent long-running processes from blocking the MCP channel.
• Security: The server implements a blacklist for dangerous commands (e.g., rm -rf /, format, mkfs). Review and adjust the blacklist if needed for your environment.
• If you need to customize how output is captured or formatted, consider adjusting client-side rendering as the MCP tool returns stdout, stderr, and status information.
• For Claude Desktop or other MCP clients, ensure the client’s configuration points to the terminal-controller MCP server correctly (see README’s configuration examples).
• To enable unbuffered output for timely MCP communication, set PYTHONUNBUFFERED=1 in the environment.