MCP Terminal Server 使用说明

项目简介

MCP Terminal Server 是一个实现了 Model Context Protocol (MCP) 的服务器，专注于提供安全的终端命令执行功能。它允许大型语言模型（LLM）客户端通过标准化的 MCP 协议，安全地调用服务器执行 shell 命令，并获取命令输出。该服务器特别强调安全性，通过限制允许执行的命令、防止命令注入和设置资源限制，来保护系统安全。

主要功能点

命令执行: 允许 LLM 客户端请求执行 shell 命令。
安全控制:
- 白名单命令: 只允许执行预先配置的白名单中的命令，防止恶意命令执行。
- 防止命令注入: 阻止 shell 操作符，避免命令注入攻击。
资源控制:
- 命令超时: 设置命令执行超时时间，防止命令无限期运行。
- 输出大小限制: 限制命令输出的最大大小，防止资源耗尽。
MCP 协议支持: 完全实现了 MCP 协议，可以与任何兼容 MCP 协议的客户端进行通信。
流式输出: 支持命令输出的流式传输。

安装步骤

安装 UV (推荐): 如果还没有安装 UV，推荐使用 UV 来管理 Python 环境和包。
```
pip install uv
```

安装 MCP Terminal Server: 使用 UV 安装 'mcp-terminal' 包。

uv pip install mcp-terminal

服务器配置

MCP 服务器需要配置在 MCP 客户端中才能使用。以 Claude Desktop 为例，需要在 'claude_desktop_config.json' 文件中配置 MCP 服务器信息。以下是一个示例配置，请根据你的实际需求修改 'args' 中的参数。

{
  "mcpServers": {
    "terminal": {  // 服务器名称，可以自定义，客户端通过此名称引用
      "command": "uv",  // 启动服务器的命令，这里使用 uv pip run 运行 mcp-terminal
      "args": [
        "pip",
        "run",
        "mcp-terminal", // 运行 mcp-terminal 包
        "--allowed-commands", // 允许执行的命令白名单，多个命令用逗号分隔
        "python,pip,git,ls,cd",
        "--timeout-ms",   // 命令执行超时时间，单位毫秒
        "30000",
        "--max-output-size", // 最大输出大小，单位字节
        "1048576"
      ]
    }
  }
}

配置参数说明:

'"terminal"': 服务器的名称，客户端将使用此名称来引用和调用该服务器。你可以自定义服务器名称。
'"command": "uv"': 启动服务器的命令。这里配置为 'uv'，假设你已经安装了 'uv' 并将其添加到 PATH 环境变量中。如果使用 'python' 直接运行，可以修改为 '"command": "python"'，并相应调整 'args'。
'"args"': 传递给启动命令的参数列表。
- '"pip", "run", "mcp-terminal"': 使用 'uv pip run' 命令来运行 'mcp-terminal' 包。
- '"--allowed-commands", "python,pip,git,ls,cd"': 重要安全配置，设置允许执行的命令白名单。请根据实际需要配置允许 LLM 调用的命令，并用逗号分隔。在生产环境中，务必设置此项以限制可执行的命令，避免安全风险。
- '"--timeout-ms", "30000"': 设置命令执行的超时时间为 30000 毫秒 (30 秒)。可以根据命令执行的预期时间调整。
- '"--max-output-size", "1048576"': 设置命令输出的最大大小为 1048576 字节 (1MB)。限制输出大小可以防止某些命令产生过多的输出导致内存耗尽。

注意: 请根据你的实际环境和安全需求，仔细配置 'allowed-commands' 参数，只允许必要的命令，并设置合理的 'timeout-ms' 和 'max-output-size'。

基本使用方法

配置完成后，在支持 MCP 协议的 LLM 客户端中（例如 Claude Desktop），你就可以通过配置的服务器名称 '"terminal"' 来调用 'run_command' 工具执行 shell 命令了。

例如，在 LLM 客户端中，可以构造一个 MCP 请求，调用 '"terminal"' 服务器的 '"run_command"' 工具，并传递要执行的命令作为参数。服务器会执行该命令，并将结果（包括退出码、标准输出、标准错误等）返回给客户端。

请参考 MCP 客户端的文档，了解如何配置和使用 MCP 服务器。

关键词