关键词

终端控制文件管理AI工具LLM集成命令执行

项目简介

MCP 终端服务器是一个基于 Model Context Protocol (MCP) 的后端应用，旨在让 LLM 和 AI 助手能够安全、标准地访问和控制用户的终端环境。通过这个服务器，AI 可以执行命令行指令、读取/写入文件，从而完成更复杂的任务，如代码编译、系统信息查询、文件编辑等。

主要功能点

  • 终端命令执行: 允许 AI 在服务器运行的终端中执行任意命令行指令，并获取输出结果。
  • 文件操作: 提供对文件进行写入、追加、插入内容的能力，支持创建目录。
  • 多种终端控制器: 根据操作系统和安装情况，自动选择或手动指定不同的终端控制方式（如 macOS 上的 iTerm2、AppleScript 控制器，或跨平台的 Subprocess 控制器）。
  • 多种传输模式: 支持通过标准输入/输出 (stdio) 或 HTTP 的 Server-Sent Events (SSE) 与 MCP 客户端通信。
  • 使用官方 MCP SDK: 基于标准协议实现，确保与兼容 MCP 的客户端（如 Claude Desktop）无缝集成。
  • Docker 支持: 提供 Docker 镜像，方便快速部署和隔离运行环境。

安装步骤

  1. 安装先决条件: 确保系统已安装 Python 3.8 或更高版本。推荐使用 'uv' 工具进行包管理，如果未安装，可以通过 'pip install uv' 或其他方式安装。
  2. 克隆仓库: 
    git clone https://github.com/sichang824/mcp-terminal.git
cd mcp-terminal
  3. 安装依赖:
    • 使用 'uv' 安装（推荐）： 
      uv venv
source .venv/bin/activate # 或在 Windows 上使用 .venv\Scripts\activate
uv pip install -e .
# 如果需要iTerm2支持 (仅macOS): uv pip install -e ".[iterm]"
    • 使用 'Makefile' 安装： 
      make setup
# 如果需要iTerm2支持: make setup-iterm
  4. Docker 安装 (可选): 如果希望使用 Docker 部署，可以构建镜像： 
    docker build -t mcp-terminal .

服务器配置 (供 MCP 客户端使用)

MCP 服务器需要由兼容的 MCP 客户端（如 Claude Desktop）启动和管理。客户端通常通过一个配置文件来定义可用的 MCP 服务器。对于 MCP 终端服务器，客户端需要配置服务器的名称、启动命令及其参数。

以下是一个配置示例的说明，展示了客户端配置文件中关于 MCP 终端服务器的部分（实际配置方式可能因客户端而异）：

一个典型的 MCP 客户端配置文件片段可能包含一个 'mcpServers' 或类似的 JSON 对象，其中每个键值对定义了一个 MCP 服务器：

{
  "mcpServers": {
    "your_server_name": { // 为这个MCP服务器定义一个在客户端内部使用的唯一名称，例如 "terminal"
      "command": "/path/to/python", // 指定用于启动服务器的可执行文件路径，通常是Python解释器
      "args": [ // 一个字符串数组，包含传递给 command 的参数
        "/path/to/mcp-terminal/mcp_terminal.py", // MCP终端服务器的入口脚本路径
        "--mode", "stdio", // 指定服务器的通信模式，这里是 stdio
        "--controller", "subprocess" // 指定使用的终端控制器类型，这里是 subprocess
        // 可以根据需要添加其他命令行参数，如 --log-level 等
      ],
      "stdio": true // 如果使用 stdio 模式，通常需要额外标记，表示客户端通过标准输入输出来与服务器通信
      // 如果使用 sse 模式，这里可能需要配置 "url": "http://localhost:8000/mcp" 等
    }
  }
}

在上面的 JSON 结构中：

  • '"your_server_name"': 这是您在 MCP 客户端中给这个终端服务器起的名字，方便在客户端界面或对话中引用。
  • '"command"': 指定了客户端用来启动 MCP 终端服务器进程的命令，通常是 Python 解释器的路径。
  • '"args"': 是一个列表，包含了启动服务器时需要传递的所有命令行参数，如指定运行脚本、模式、控制器等。
  • '"stdio": true' 或其他模式相关的配置：告诉客户端如何与启动的服务器进程建立连接（通过标准流或网络）。

请根据您实际的 Python 解释器路径、'mcp_terminal.py' 脚本路径以及希望使用的服务器模式和控制器来修改这些配置值。

基本使用方法

  1. 运行服务器:
    • 直接运行: 在项目根目录执行 'python mcp_terminal.py' (默认 stdio 模式和自动控制器)。可以使用 'make run-stdio' 或 'make run-sse' 方便运行不同模式。
    • Docker 运行: 构建镜像后，使用 'docker run -p 8000:8000 mcp-terminal' 可以在 SSE 模式下运行服务器，并将容器端口映射到宿主机。
  2. 集成到 MCP 客户端: 根据上方“服务器配置”部分，将 MCP 终端服务器的启动信息添加到您的 MCP 客户端（如 Claude Desktop）的配置中。
  3. 在 AI 对话中使用: 一旦服务器在客户端中成功配置并启动，您就可以在与 AI 的对话中，通过客户端的工具调用功能，请求 AI 执行终端命令或进行文件操作。例如，您可以对 AI 说：“请使用终端执行 'ls -l /' 命令并告诉我结果”，或者“请在当前目录下创建一个名为 'hello.txt' 的文件，内容是 'Hello, World!'”。

关键词

终端控制, 文件管理, AI工具, LLM集成, 命令执行

信息

分类

开发者工具

访问项目