MCP终端控制器

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

功能特性

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

安装指南

通过Smithery安装

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

npx -y @smithery/cli install @GongRzhe/terminal-controller-mcp --client claude

前提条件

• Python 3.11或更高版本
• 兼容MCP的客户端（如Claude Desktop）
• UV/UVX（可选，用于UVX方法）

方法一：PyPI安装（推荐）

直接从PyPI安装包：

pip install terminal-controller

或使用UV安装：

uv pip install terminal-controller

方法二：从源码安装

如果希望从源码安装：

1. 克隆仓库：

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

2. 运行安装脚本：

   python setup_mcp.py
   

客户端配置

Claude Desktop

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

选项一：使用UVX（推荐）

在Claude Desktop配置文件中添加：

"terminal-controller": {
  "command": "uvx",
  "args": ["terminal_controller"]
}

选项二：直接使用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"
• "导航到我的文档文件夹"
• "显示我的下载目录内容"
• "显示我最近的命令历史"
• "读取config.json的内容"
• "将script.py文件的第5行更新为'print("Hello World")'"
• "从日志文件中删除第10-15行"
• "在我的文本文件开头插入新行"

API参考

终端控制器提供以下MCP工具：

execute_command

执行终端命令并返回结果。

参数：

• command：要执行的命令行命令
• timeout：命令超时时间（秒，默认：30）

返回：

• 命令执行结果，包括标准输出、标准错误和执行状态

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开始，可选）

返回：

• 操作结果信息

安全考虑

终端控制器实现了多项安全措施：

• 超时控制防止长时间运行的命令
• 危险命令黑名单（如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