用于 MCP 的终端控制器

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

功能特性

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

安装

前提条件

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

方法 1：PyPI 安装（推荐）

直接从 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
   

2. 运行安装脚本：

   python setup_mcp.py
   

客户端配置

Claude Desktop

有两种方法可以配置 Claude Desktop 以使用 Terminal Controller：

选项 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.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Cursor

对于 Cursor，使用与 Claude Desktop 类似的配置设置。

其他 MCP 客户端

对于其他客户端，请参阅其文档，了解如何配置外部 MCP 服务器。

用法

配置完成后，您可以使用自然语言通过 MCP 客户端与终端进行交互：

• "在当前目录中运行命令 ls -la"
• "导航到我的 Documents 文件夹"
• "显示我的 Downloads 目录的内容"
• "显示我最近的命令历史"
• "读取 config.json 的内容"
• "使用 'print("Hello World")' 更新我的 script.py 文件中的第 5 行"
• "从日志文件中删除第 10-15 行"
• "在我的文本文件的开头插入一个新行"

API 参考

Terminal Controller 公开了以下 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: 写入模式（'overwrite' 或 'append'，默认值：'overwrite'）

返回值：

• 操作结果信息，包括成功写入的验证

read_file

从文件中读取内容，具有可选的行选择。

参数：

• path: 文件的路径
• start_row: 要从中读取的起始行（从 0 开始，可选）
• end_row: 要读取到的结束行（从 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 开始，可选）

返回值：

• 操作结果信息

安全注意事项

Terminal Controller 实施了多项安全措施：

• 超时控制以防止长时间运行的命令
• 危险命令的黑名单（rm -rf /, format, mkfs）
• 正确的错误处理和命令执行隔离
• 仅访问专门授予的命令和目录

局限性

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

故障排除

如果您遇到问题：

1. 检查您的 Python 版本是否为 3.11 或更高版本
2. 验证您的 Claude Desktop 配置是否正确
3. 尝试直接运行终端控制器以检查错误：

   python -m terminal_controller
   

4. 对于与 UVX 相关的问题，请尝试：

   uvx terminal_controller
   

5. 查看 MCP 客户端的日志以查找连接错误

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

MIT