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方法）

方法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以使用终端控制器：

选项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"
• "导航到我的文档文件夹"
• "显示我下载目录的内容"
• "显示我最近的命令历史"
• "读取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：写入模式（'覆盖'或'追加'，默认值：'覆盖'）

返回：

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

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