Skip to content
Back to search

terminal-controller-mcp

A Model Context Protocol (MCP) server that enables secure terminal command execution, directory navigation, and file system operations through a standardized interface.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gongrzhe--terminal-controller-mcp/badge.svg)](/listings/gongrzhe--terminal-controller-mcp)

HTML

<a href="/listings/gongrzhe--terminal-controller-mcp"><img src="/api/listings/gongrzhe--terminal-controller-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Installing via Smithery

To install Terminal Controller for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@GongRzhe/terminal-controller-mcp):

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 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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 264 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Terminal Controller for MCP
  2. A Model Context Protocol (MCP) server that enables secure terminal command execution, directory navigation, and file system operations through a standardized interface.
  3. ![](https://badge.mcpx.dev?type=server 'MCP Server')
  4. [![smithery badge](https://smithery.ai/badge/@GongRzhe/terminal-controller-mcp)](https://smithery.ai/server/@GongRzhe/terminal-controller-mcp)
  5. ## Features
  6. - **Command Execution**: Run terminal commands with timeout controls and comprehensive output capture
  7. - **Directory Management**: Navigate and list directory contents with intuitive formatting
  8. - **Security Measures**: Built-in safeguards against dangerous commands and operations
  9. - **Command History**: Track and display recent command executions
  10. - **Cross-Platform Support**: Works on both Windows and UNIX-based systems
  11. - **File Operations**: Read, write, update, insert, and delete file content with row-level precision
  12. ## Installation
  13. ### Installing via Smithery
  14. To install Terminal Controller for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@GongRzhe/terminal-controller-mcp):
  15. ```bash
  16. npx -y @smithery/cli install @GongRzhe/terminal-controller-mcp --client claude
  17. ```
  18. ### Prerequisites
  19. - Python 3.11+
  20. - An MCP-compatible client (such as Claude Desktop)
  21. - UV/UVX installed (optional, for UVX method)
  22. ### Method 1: PyPI Installation (Recommended)
  23. Install the package directly from PyPI:
  24. ```bash
  25. pip install terminal-controller
  26. ```
  27. Or if you prefer to use UV:
  28. ```bash
  29. uv pip install terminal-controller
  30. ```
  31. ### Method 2: From Source
  32. If you prefer to install from source:
  33. 1. Clone this repository:
  34. ```bash
  35. git clone https://github.com/GongRzhe/terminal-controller-mcp.git
  36. cd terminal-controller-mcp
  37. ```
  38. 2. Run the setup script:
  39. ```bash
  40. python setup_mcp.py
  41. ```
  42. ## Client Configuration
  43. ### Claude Desktop
  44. There are two ways to configure Claude Desktop to use Terminal Controller:
  45. #### Option 1: Using UVX (Recommended)
  46. Add this to your Claude Desktop configuration file:
  47. ```json
  48. "terminal-controller": {
  49. "command": "uvx",
  50. "args": ["terminal_controller"]
  51. }
  52. ```
  53. #### Option 2: Using Python Directly
  54. ```json
  55. "terminal-controller": {
  56. "command": "python",
  57. "args": ["-m", "terminal_controller"]
  58. }
  59. ```
  60. The configuration path varies by operating system:
  61. - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  62. - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  63. ### Cursor
  64. For Cursor, use similar configuration settings as Claude Desktop.
  65. ### Other MCP Clients
  66. For other clients, refer to their documentation on how to configure external MCP servers.
  67. ## Usage
  68. Once configured, you can use natural language to interact with your terminal through your MCP client:
  69. - "Run the command `ls -la` in the current directory"
  70. - "Navigate to my Documents folder"
  71. - "Show me the contents of my Downloads directory"
  72. - "Show me my recent command history"
  73. - "Read the content of config.json"
  74. - "Update line 5 in my script.py file with 'print(\"Hello World\")'"
  75. - "Delete lines 10-15 from the log file"
  76. - "Insert a new line at the beginning of my text file"
  77. ## API Reference
  78. Terminal Controller exposes the following MCP tools:
  79. ### `execute_command`
  80. Execute a terminal command and return its results.
  81. **Parameters:**
  82. - `command`: The command line command to execute
  83. - `timeout`: Command timeout in seconds (default: 30)
  84. **Returns:**
  85. - Output of the command execution, including stdout, stderr, and execution status
  86. ### `get_command_history`
  87. Get recent command execution history.
  88. **Parameters:**
  89. - `count`: Number of recent commands to return (default: 10)
  90. **Returns:**
  91. - Formatted command history record
  92. ### `get_current_directory`
  93. Get the current working directory.
  94. **Returns:**
  95. - Path of current working directory
  96. ### `change_directory`
  97. Change the current working directory.
  98. **Parameters:**
  99. - `path`: Directory path to switch to
  100. **Returns:**
  101. - Operation result information
  102. ### `list_directory`
  103. List files and subdirectories in the specified directory.
  104. **Parameters:**
  105. - `path`: Directory path to list contents (default: current directory)
  106. **Returns:**
  107. - List of directory contents, formatted with icons for directories and files
  108. ### `write_file`
  109. Write content to a file with overwrite or append options.
  110. **Parameters:**
  111. - `path`: Path to the file
  112. - `content`: Content to write
  113. - `mode`: Write mode ('overwrite' or 'append', default: 'overwrite')
  114. **Returns:**
  115. - Operation result information including verification of successful write
  116. ### `read_file`
  117. Read content from a file with optional row selection.
  118. **Parameters:**
  119. - `path`: Path to the file
  120. - `start_row`: Starting row to read from (0-based, optional)
  121. - `end_row`: Ending row to read to (0-based, inclusive, optional)
  122. **Returns:**
  123. - File content or selected lines
  124. ### `insert_file_content`
  125. Insert content at specific row(s) in a file.
  126. **Parameters:**
  127. - `path`: Path to the file
  128. - `content`: Content to insert
  129. - `row`: Row number to insert at (0-based, optional)
  130. - `rows`: List of row numbers to insert at (0-based, optional)
  131. **Returns:**
  132. - Operation result information
  133. ### `delete_file_content`
  134. Delete content at specific row(s) from a file.
  135. **Parameters:**
  136. - `path`: Path to the file
  137. - `row`: Row number to delete (0-based, optional)
  138. - `rows`: List of row numbers to delete (0-based, optional)
  139. **Returns:**
  140. - Operation result information
  141. ### `update_file_content`
  142. Update content at specific row(s) in a file.
  143. **Parameters:**
  144. - `path`: Path to the file
  145. - `content`: New content to place at the specified row(s)
  146. - `row`: Row number to update (0-based, optional)
  147. - `rows`: List of row numbers to update (0-based, optional)
  148. **Returns:**
  149. - Operation result information
  150. ## Security Considerations
  151. Terminal Controller implements several security measures:
  152. - Timeout controls to prevent long-running commands
  153. - Blacklisting of dangerous commands (rm -rf /, format, mkfs)
  154. - Proper error handling and isolation of command execution
  155. - Access only to the commands and directories specifically granted
  156. ## Limitations
  157. - Only commands that complete within the timeout period will return results
  158. - By default, the server has access to the same file system permissions as the user running it
  159. - Some interactive commands may not work as expected due to the non-interactive nature of the terminal interface
  160. ## Troubleshooting
  161. If you encounter issues:
  162. 1. Check that your Python version is 3.11 or higher
  163. 2. Verify that your Claude Desktop configuration is correct
  164. 3. Try running the terminal controller directly to check for errors:
  165. ```bash
  166. python -m terminal_controller
  167. ```
  168. 4. For UVX-related issues, try:
  169. ```bash
  170. uvx terminal_controller
  171. ```
  172. 5. Review your MCP client's logs for connection errors
  173. ## Contributing
  174. Contributions are welcome! Please feel free to submit a Pull Request.
  175. ## License
  176. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.