Terminal Controller for MCP

基本能力

产品定位

Terminal Controller for MCP 是一个基于模型上下文协议（MCP）的服务，旨在通过标准化接口实现安全的终端命令执行、目录导航和文件系统操作。

核心功能

• 命令执行：支持带超时控制的终端命令执行，并捕获完整的输出。
• 目录管理：提供直观的目录内容列表和导航功能。
• 安全措施：内置对危险命令和操作的保护机制。
• 命令历史：记录和显示最近的命令执行记录。
• 跨平台支持：兼容 Windows 和 UNIX 系统。
• 文件操作：支持文件的读取、写入、更新、插入和删除操作，精确到行级别。

适用场景

• 通过自然语言交互执行终端命令。
• 管理文件和目录，包括导航、列表、读取和修改文件内容。
• 自动化开发流程中的终端操作。

工具列表

• execute_command：执行终端命令并返回结果。
• get_command_history：获取最近的命令执行历史。
• get_current_directory：获取当前工作目录。
• change_directory：切换当前工作目录。
• list_directory：列出指定目录的内容。
• write_file：写入文件内容，支持覆盖或追加模式。
• read_file：读取文件内容，可选行选择。
• insert_file_content：在文件中插入内容。
• delete_file_content：删除文件中的内容。
• update_file_content：更新文件中的内容。

常见问题解答

• 确保 Python 版本为 3.11 或更高。
• 检查 Claude Desktop 配置是否正确。
• 直接运行终端控制器以检查错误。
• 对于 UVX 相关问题，尝试使用 UVX 命令。
• 查看 MCP 客户端的日志以获取连接错误信息。

使用教程

使用依赖

• Python 3.11+
• MCP 兼容客户端（如 Claude Desktop）
• UV/UVX（可选，用于 UVX 方法）

安装教程

方法 1: PyPI 安装（推荐）

pip install terminal-controller

或使用 UV：

uv pip install terminal-controller

方法 2: 从源码安装

1. 克隆仓库：

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

1. 运行安装脚本：

python setup_mcp.py

调试方式

1. 检查 Python 版本：

python --version

1. 直接运行终端控制器：

python -m terminal_controller

1. 使用 UVX 运行：

uvx terminal_controller

1. 查看客户端日志以获取错误信息。

许可证

该项目遵循 MIT 开源许可条款，请参阅 MIT 了解完整条款。