Terminal Controller for MCP

MCP 终端控制器

模型上下文协议 (MCP) 服务器，通过标准化接口实现安全终端命令执行、目录导航和文件系统操作。

特征

• 命令执行：运行具有超时控制和全面输出捕获的终端命令
• 目录管理：以直观的格式导航和列出目录内容
• 安全措施：内置安全措施，防止危险命令和操作
• 命令历史记录：跟踪并显示最近的命令执行
• 跨平台支持：适用于 Windows 和基于 UNIX 的系统
• 文件操作：以行级精度读取、写入、更新、插入和删除文件内容

安装

通过 Smithery 安装

要通过Smithery自动安装 Claude Desktop 的终端控制器：

先决条件

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

方法 1：PyPI 安装（推荐）

直接从 PyPI 安装包：

或者如果您更喜欢使用 UV：

方法 2：从源

如果您希望从源代码安装：

1. 克隆此存储库：
   git clone https://github.com/GongRzhe/terminal-controller-mcp.git cd terminal-controller-mcp
2. 运行安装脚本：
   python setup_mcp.py

客户端配置

克劳德桌面

有两种方法可以配置 Claude Desktop 使用终端控制器：

选项 1：使用 UVX（推荐）

将其添加到您的 Claude Desktop 配置文件中：

选项 2：直接使用 Python

配置路径因操作系统而异：

• macOS ： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows ： %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）
• 正确的错误处理和命令执行的隔离
• 仅访问明确授予的命令和目录

限制

• 只有在超时时间内完成的命令才会返回结果
• 默认情况下，服务器具有与运行它的用户相同的文件系统权限
• 由于终端界面的非交互特性，某些交互式命令可能无法按预期工作

故障排除

如果您遇到问题：

1. 检查你的 Python 版本是否为 3.11 或更高版本
2. 验证您的 Claude Desktop 配置是否正确
3. 尝试直接运行终端控制器来检查错误：
   python -m terminal_controller
4. 对于与 UVX 相关的问题，请尝试：
   uvx terminal_controller
5. 检查 MCP 客户端日志中的连接错误

贡献

欢迎贡献代码！欢迎提交 Pull 请求。

执照

麻省理工学院