by GongRzhe
Enables secure execution of terminal commands, directory navigation, and precise file system operations through a standardized interface.
Terminal Controller provides a Model Context Protocol (MCP) server that allows natural‑language interaction with the local shell. Users can run commands, change directories, list files, and perform fine‑grained file edits (read, write, insert, update, delete) without typing raw terminal commands.
pip install terminal-controller
# or using UV
uv pip install terminal-controller
python -m terminal_controller
ls -la
”, “Show me my recent command history”, or “Update line 5 in script.py
with print('Hello World')
”.Q: Which Python version is required? A: Python 3.11 or newer.
Q: How are dangerous commands prevented?
A: The server maintains a blacklist (e.g., rm -rf /
, format
, mkfs
) and enforces execution timeouts.
Q: Can interactive commands like ssh
be used?
A: Interactive commands may not work correctly because the server runs commands in a non‑interactive subprocess.
Q: How do I configure Claude Desktop to use the server?
A: Add a JSON entry in the Claude Desktop config file pointing to the command python -m terminal_controller
(or uvx terminal_controller
).
Q: Is there a Node.js alternative? A: The current implementation is Python‑based; no Node.js package is provided.
A Model Context Protocol (MCP) server that enables secure terminal command execution, directory navigation, and file system operations through a standardized interface.
To install Terminal Controller for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @GongRzhe/terminal-controller-mcp --client claude
Install the package directly from PyPI:
pip install terminal-controller
Or if you prefer to use UV:
uv pip install terminal-controller
If you prefer to install from source:
Clone this repository:
git clone https://github.com/GongRzhe/terminal-controller-mcp.git
cd terminal-controller-mcp
Run the setup script:
python setup_mcp.py
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"]
}
"terminal-controller": {
"command": "python",
"args": ["-m", "terminal_controller"]
}
The configuration path varies by operating system:
~/Library/Application Support/Claude/claude_desktop_config.json
%APPDATA%\Claude\claude_desktop_config.json
For Cursor, use similar configuration settings as Claude Desktop.
For other clients, refer to their documentation on how to configure external MCP servers.
Once configured, you can use natural language to interact with your terminal through your MCP client:
ls -la
in the current directory"Terminal Controller exposes the following MCP tools:
execute_command
Execute a terminal command and return its results.
Parameters:
command
: The command line command to executetimeout
: Command timeout in seconds (default: 30)Returns:
get_command_history
Get recent command execution history.
Parameters:
count
: Number of recent commands to return (default: 10)Returns:
get_current_directory
Get the current working directory.
Returns:
change_directory
Change the current working directory.
Parameters:
path
: Directory path to switch toReturns:
list_directory
List files and subdirectories in the specified directory.
Parameters:
path
: Directory path to list contents (default: current directory)Returns:
write_file
Write content to a file with overwrite or append options.
Parameters:
path
: Path to the filecontent
: Content to writemode
: Write mode ('overwrite' or 'append', default: 'overwrite')Returns:
read_file
Read content from a file with optional row selection.
Parameters:
path
: Path to the filestart_row
: Starting row to read from (0-based, optional)end_row
: Ending row to read to (0-based, inclusive, optional)Returns:
insert_file_content
Insert content at specific row(s) in a file.
Parameters:
path
: Path to the filecontent
: Content to insertrow
: Row number to insert at (0-based, optional)rows
: List of row numbers to insert at (0-based, optional)Returns:
delete_file_content
Delete content at specific row(s) from a file.
Parameters:
path
: Path to the filerow
: Row number to delete (0-based, optional)rows
: List of row numbers to delete (0-based, optional)Returns:
update_file_content
Update content at specific row(s) in a file.
Parameters:
path
: Path to the filecontent
: 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:
Terminal Controller implements several security measures:
If you encounter issues:
python -m terminal_controller
uvx terminal_controller
Contributions are welcome! Please feel free to submit a Pull Request.
MIT
Please log in to share your review and rating for this MCP.
{ "mcpServers": { "terminal-controller": { "command": "python", "args": [ "-m", "terminal_controller" ], "env": {} } } }
Discover more MCP servers with similar functionality and use cases
by Skyvern-AI
Skyvern automates browser-based workflows using LLMs and computer vision, offering a robust solution for repetitive online tasks.
by PipedreamHQ
Connect APIs quickly, run event‑driven automations, and execute custom code in Node.js, Python, Go, or Bash on a hosted platform.
by czlonkowski
Provides AI assistants with structured access to n8n node documentation, properties, and operations, enabling automated workflow creation, validation, and management.
by executeautomation
mcp-playwright is a Model Context Protocol (MCP) server that enables large language models (LLMs) to perform browser automation and web scraping tasks using Playwright.
by browserbase
Provides cloud browser automation capabilities for LLMs, enabling web navigation, interaction, screenshot capture, and data extraction through Browserbase and Stagehand.
by haris-musa
excel-mcp-server is a Python-based Model Context Protocol (MCP) server that enables AI agents to programmatically create, read, and modify Excel files without requiring Microsoft Excel to be installed.
by mobile-next
Mobile-mcp is a Model Context Protocol (MCP) server designed for scalable mobile automation, app scraping, and development across iOS and Android devices, including physical devices, simulators, and emulators.
by anaisbetts
mcp-installer is an MCP server designed to automate the installation of other MCP servers, simplifying the process for users.
by leonardsellem
An MCP server that enables AI assistants to interact with n8n workflows through natural language.