HelloWorld
登录
终

终端控制器MCP

一个MCP服务器，通过为LLMs提供的标准化接口，实现安全的终端命令执行、目录导航和文件系统操作。

os-automationfile-systems

1.5k 查看 · 2026-07-07 更新

简介

一个MCP服务器，通过为LLMs提供的标准化接口，实现安全的终端命令执行、目录导航和文件系统操作。

简介

一个MCP服务器，通过为LLMs提供的标准化接口，实现安全的终端命令执行、目录导航和文件系统操作。

终端控制器 for MCP

一个 Model Context Protocol (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 使用终端控制器：

选项 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 的内容"
  • "将我的 script.py 文件中的第 5 行更新为 'print("Hello World")'"
  • "从日志文件中删除第 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: 写入模式（'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

来源