使用说明

项目简介

Terminal Controller 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在为大型语言模型 (LLM) 提供安全可控的本地终端访问能力。通过 Terminal Controller，LLM 客户端可以执行终端命令、浏览文件系统、管理目录，从而实现更强大的本地资源操作和自动化任务。

主要功能点

安全命令执行: 允许 LLM 安全地执行终端命令，并提供超时控制和详细的输出信息。
目录管理: 支持 LLM 浏览和切换目录，方便进行文件系统操作。
文件列表: 允许 LLM 获取指定目录下的文件和子目录列表，并以易读的格式呈现。
命令历史: 记录最近执行的命令历史，方便 LLM 查询和审计。
跨平台支持: 兼容 Windows 和 UNIX-based 系统。

安装步骤

推荐使用自动化安装脚本，简单快捷：

克隆仓库

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

运行安装脚本
```
python setup_mcp.py
```
该脚本会自动创建 Python 虚拟环境、安装依赖，并生成 MCP 配置文件。

如果需要手动安装，请参考仓库 README.md 中的 "Manual Setup (Alternative)" 部分。

服务器配置

Terminal Controller 是一个 MCP 服务器，需要配置在 MCP 客户端中才能使用。以下是配置示例，以 JSON 格式展示，你需要将配置信息添加到你的 MCP 客户端配置文件中。

通用配置 (以 Claude Desktop 为例):

{
  "mcpServers": {
    "terminal-controller": {
      "command": "/path/to/terminal-controller/.venv/bin/python",
      "args": [
        "/path/to/terminal-controller/terminal_controller.py"
      ],
      "env": {
        "PYTHONPATH": "/path/to/terminal-controller"
      }
    }
  }
}

配置参数说明:

'"terminal-controller"': 服务器名称，可以自定义，用于在客户端中标识该服务器。
'"command"': 必需。指向 Python 解释器的路径。如果你使用自动化安装脚本 'setup_mcp.py'，该路径将位于项目目录下的 '.venv' 虚拟环境中。你需要将 '/path/to/terminal-controller' 替换为你的 仓库实际路径。 Windows 系统下，路径可能为 '/path/to/terminal-controller/.venv/Scripts/python.exe'。
'"args"': 必需。一个字符串数组，包含服务器启动参数。这里指定了 'terminal_controller.py' 脚本的路径。同样需要将 '/path/to/terminal-controller' 替换为你的 仓库实际路径。
'"env"': 可选。环境变量配置。 'PYTHONPATH' 指定了 Python 模块的搜索路径，确保服务器程序能找到 'mcp' 库。

重要提示:

请务必将配置示例中的 '/path/to/terminal-controller' 替换为你 本地仓库的绝对路径。
不同的 MCP 客户端配置文件的位置和格式可能有所不同，请参考你使用的 MCP 客户端的文档进行配置。例如 Claude Desktop 的配置文件路径通常为：
- macOS: '~/Library/Application Support/Claude/claude_desktop_config.json'
- Windows: '%APPDATA%\Claude\claude_desktop_config.json'

基本使用方法

配置完成后，在你的 MCP 客户端中，你可以使用自然语言指令来控制终端。例如：

"运行命令 'ls -la' 查看当前目录的文件"
"切换到 'Documents' 目录"
"列出 'Downloads' 目录下的文件"
"查看最近的命令历史"

具体的指令格式取决于你使用的 MCP 客户端的自然语言理解能力。

关键词