Terminal Controller
A Model Context Protocol (MCP) server that enables secure terminal command execution, directory navigation, and file system operations through a standardized interface.
What is Terminal Controller?
Terminal Controller is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to model context protocol (mcp) server that enables secure terminal command execution, directory navigation, and file system operations through a standardized interface.
A Model Context Protocol (MCP) server that enables secure terminal command execution, directory navigation, and file system operations through a standardized interface.
This server falls under the Developer Tools category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- A Model Context Protocol (MCP) server that enables secure te
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx terminal-controller-for-mcpConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Terminal Controller
Terminal Controller for MCP is a Python-based MCP server that gives AI assistants secure, structured access to terminal command execution, directory navigation, and file system operations through a standardized interface. It exposes 10 discrete tools covering everything from running shell commands with timeout controls to reading, writing, inserting, updating, and deleting specific lines within files — making it a comprehensive coding and automation assistant. It is installable via pip or uvx and integrates directly with Claude Desktop and other MCP clients.
Prerequisites
- Python 3.10+ installed
- pip or uv package manager available
- An MCP-compatible client such as Claude Desktop or Cursor
- Appropriate system permissions for the directories the AI will operate on
Install Terminal Controller via pip or uvx
Install the terminal-controller package. The uvx method is recommended as it handles isolated execution automatically.
pip install terminal-controller
# OR using uv:
uv pip install terminal-controllerAlternatively, install via Smithery for automatic client setup
Smithery can install and configure the server for Claude Desktop in one command.
npx -y @smithery/cli install @GongRzhe/terminal-controller-mcp --client claudeConfigure Claude Desktop manually (if not using Smithery)
Add Terminal Controller to your Claude Desktop configuration file. The uvx method is the simplest to configure as it requires no explicit path.
Restart Claude Desktop
Quit and relaunch Claude Desktop to load the new MCP server. All 10 terminal tools will become available in your conversation.
Verify tools are accessible
Ask Claude to list the current directory or run a simple command. You should see it invoke the list_directory or execute_command tool.
Terminal Controller Examples
Client configuration
Claude Desktop config using the recommended uvx method for running Terminal Controller.
{
"mcpServers": {
"terminal-controller": {
"command": "uvx",
"args": ["terminal_controller"]
}
}
}Prompts to try
Example prompts that use the full range of Terminal Controller's 10 tools.
- "Run 'ls -la' in the current directory and show me what's there"
- "Navigate to ~/projects/myapp and then run 'npm test'"
- "Read lines 1-50 of src/main.py"
- "Update line 12 in config.json to set 'debug': true"
- "Delete lines 100-115 from the server log file"
- "Show me the command history from this session"Troubleshooting Terminal Controller
execute_command times out on long-running processes
The execute_command tool has configurable timeout controls. For long-running commands (builds, tests), specify a higher timeout value in the tool call arguments. Alternatively, structure your workflow to use shorter discrete commands.
Permission denied errors when running commands
The MCP server inherits the permissions of the process that launched it (Claude Desktop or the shell). Ensure the Claude Desktop process has read/write access to the directories you are trying to operate on, or run with appropriate user privileges.
uvx command not found after installing uv
After installing uv (pip install uv), ensure the uv bin directory is in your PATH. Run 'uv --version' to verify installation. If uvx is missing, upgrade uv with 'pip install --upgrade uv'.
Frequently Asked Questions about Terminal Controller
What is Terminal Controller?
Terminal Controller is a Model Context Protocol (MCP) server that model context protocol (mcp) server that enables secure terminal command execution, directory navigation, and file system operations through a standardized interface. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Terminal Controller?
Follow the installation instructions on the Terminal Controller GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Terminal Controller?
Terminal Controller works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Terminal Controller free to use?
Yes, Terminal Controller is open source and available under the MIT License license. You can use it freely in both personal and commercial projects.
Terminal Controller Alternatives — Similar Developer Tools Servers
Looking for alternatives to Terminal Controller? Here are other popular developer tools servers you can use with Claude, Cursor, and VS Code.
Ecc
★ 188.2kThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Javaguide
★ 155.8kJava 面试 & 后端通用面试指南，覆盖计算机基础、数据库、分布式、高并发、系统设计与 AI 应用开发
Gemini CLI
★ 104.5kA secure MCP server that wraps the Google Gemini CLI, allowing clients to query Gemini models using local OAuth sessions without requiring an API key. It provides tools for model interaction and diagnostics with built-in protection against command in
Awesome MCP Servers
★ 87.3k⭐ Curated list of Model Context Protocol (MCP) servers - tools that extend Claude Desktop, Cursor, Windsurf, and other MCP clients with custom capabilities.
MCP Servers
★ 86.0kModel Context Protocol Servers
CC Switch
★ 77.5kA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Gemini CLI & Hermes Agent. Only official website: ccswitch.io
Browse More Developer Tools MCP Servers
Explore all developer tools servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Terminal Controller in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Terminal Controller?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.