Terminal Controller for MCP
MCP 终端控制器
模型上下文协议 (MCP) 服务器,通过标准化接口实现安全终端命令执行、目录导航和文件系统操作。
特征
命令执行:运行具有超时控制和全面输出捕获的终端命令
目录管理:以直观的格式导航和列出目录内容
安全措施:内置安全措施,防止危险命令和操作
命令历史记录:跟踪并显示最近的命令执行
跨平台支持:适用于 Windows 和基于 UNIX 的系统
文件操作:以行级精度读取、写入、更新、插入和删除文件内容
Related MCP server: MCP Server
安装
通过 Smithery 安装
要通过Smithery自动安装 Claude Desktop 的终端控制器:
npx -y @smithery/cli install @GongRzhe/terminal-controller-mcp --client claude先决条件
Python 3.11+
与 MCP 兼容的客户端(例如 Claude Desktop)
安装 UV/UVX(可选,用于 UVX 方法)
方法 1:PyPI 安装(推荐)
直接从 PyPI 安装包:
pip install terminal-controller或者如果您更喜欢使用 UV:
uv pip install terminal-controller方法 2:从源
如果您希望从源代码安装:
克隆此存储库:
git clone https://github.com/GongRzhe/terminal-controller-mcp.git cd terminal-controller-mcp运行安装脚本:
python setup_mcp.py
客户端配置
克劳德桌面
有两种方法可以配置 Claude Desktop 使用终端控制器:
选项 1:使用 UVX(推荐)
将其添加到您的 Claude Desktop 配置文件中:
"terminal-controller": {
"command": "uvx",
"args": ["terminal_controller"]
}选项 2:直接使用 Python
"terminal-controller": {
"command": "python",
"args": ["-m", "terminal_controller"]
}配置路径因操作系统而异:
macOS :
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows :
%APPDATA%\Claude\claude_desktop_config.json
光标
对于 Cursor,使用与 Claude Desktop 类似的配置设置。
其他 MCP 客户端
对于其他客户端,请参阅其文档以了解如何配置外部 MCP 服务器。
用法
配置完成后,您可以使用自然语言通过 MCP 客户端与您的终端进行交互:
“在当前目录中运行命令
ls -la”“导航到我的文档文件夹”
“显示我的下载目录的内容”
“显示我最近的命令历史记录”
“读取config.json的内容”
“使用‘print(“Hello World”)’更新我的 script.py 文件中的第 5 行”
“从日志文件中删除第 10 至 15 行”
“在我的文本文件的开头插入一个新行”
API 参考
终端控制器公开以下 MCP 工具:
execute_command
执行终端命令并返回其结果。
参数:
command:要执行的命令行命令timeout:命令超时(秒)(默认值:30)
返回:
命令执行的输出,包括 stdout、stderr 和执行状态
get_command_history
获取最近的命令执行历史记录。
参数:
count:返回的最近命令数(默认值:10)
返回:
格式化的命令历史记录
get_current_directory
获取当前工作目录。
返回:
当前工作目录的路径
change_directory
更改当前工作目录。
参数:
path:切换到的目录路径
返回:
操作结果信息
list_directory
列出指定目录中的文件和子目录。
参数:
path:列出内容的目录路径(默认值:当前目录)
返回:
目录内容列表,使用目录和文件的图标格式化
write_file
使用覆盖或附加选项将内容写入文件。
参数:
path:文件路径content:要写的内容mode:写入模式('覆盖'或'附加',默认值:'覆盖')
返回:
操作结果信息包括写入成功的验证
read_file
从文件中读取内容,并可选择行。
参数:
path:文件路径start_row:读取的起始行(从 0 开始,可选)end_row:读取的结束行(从 0 开始,包含 0,可选)
返回:
文件内容或选定的行
insert_file_content
在文件的特定行插入内容。
参数:
path:文件路径content:要插入的内容row:要插入的行号(从 0 开始,可选)rows:要插入的行号列表(从 0 开始,可选)
返回:
操作结果信息
delete_file_content
从文件中删除特定行的内容。
参数:
path:文件路径row:要删除的行号(从 0 开始,可选)rows:要删除的行号列表(从 0 开始,可选)
返回:
操作结果信息
update_file_content
更新文件中特定行的内容。
参数:
path:文件路径content:放置在指定行的新内容row:要更新的行号(从 0 开始,可选)rows:要更新的行号列表(从 0 开始,可选)
返回:
操作结果信息
安全注意事项
终端控制器实施了多项安全措施:
超时控制以防止长时间运行的命令
危险命令黑名单(rm -rf /、format、mkfs)
正确的错误处理和命令执行的隔离
仅访问明确授予的命令和目录
限制
只有在超时时间内完成的命令才会返回结果
默认情况下,服务器具有与运行它的用户相同的文件系统权限
由于终端界面的非交互特性,某些交互式命令可能无法按预期工作
故障排除
如果您遇到问题:
检查你的 Python 版本是否为 3.11 或更高版本
验证您的 Claude Desktop 配置是否正确
尝试直接运行终端控制器来检查错误:
python -m terminal_controller对于与 UVX 相关的问题,请尝试:
uvx terminal_controller检查 MCP 客户端日志中的连接错误
贡献
欢迎贡献代码!欢迎提交 Pull 请求。
执照
麻省理工学院
Available Tools
10 toolschange_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
Scored across 10 tools
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.
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.
With 10 tools, the set is well-scoped for a terminal controller, providing essential file and directory operations plus command execution without oversaturation.
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
Related MCP Connectors
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
The Remote MCP server acts as a standardized bridge between LLM applications (like Claude, ChatGPT, and Cursor) and external services, enabling AI agents to access external tools and resources. Its primary capability is providing a centralized search tool to discover other MCP servers and their respective tools. Unlike local implementations, it runs remotely with OAuth authentication and permission controls for security.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP 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
- AlicenseNot gradedqualityDmaintenanceA modular MCP server providing file operations, web search, URL scraping, and sandboxed command execution for LLM interactions.1MIT
- AlicenseBqualityCmaintenanceA secure MCP server for shell operations, terminal management, and process control, enabling AI assistants to safely execute commands and manage interactive sessions.13158 npm6MIT
- AlicenseNot gradedqualityBmaintenanceA local MCP server that enables LLMs to execute shell commands on remote hosts over SSH with multiple authentication methods.3MIT