CLI MCP Server 使用说明

项目简介

CLI MCP Server 是一个基于 Model Context Protocol (MCP) 构建的后端服务器，旨在为大型语言模型 (LLM) 应用提供安全的命令行 (CLI) 执行能力。它通过严格的安全策略，例如命令白名单、路径验证和操作限制，保护系统免受潜在的恶意命令注入和路径遍历攻击。此服务器允许授权的 LLM 应用安全地与底层操作系统交互，执行预定义的命令，从而扩展 LLM 的功能。

主要功能点

安全命令执行: 仅执行预先配置的白名单中的命令，防止执行未授权的命令。
可配置的命令和 Flag 白名单: 灵活配置允许执行的命令和命令选项（flags），可以使用 "all" 允许所有命令或选项。
路径安全验证: 确保所有文件路径操作都在预定义的允许目录范围内，防止访问或操作未授权的目录和文件。
防 Shell 操作符注入: 阻止使用 Shell 操作符（如 '&&', '|', '>', '>>' 等），避免复杂的、潜在危险的命令结构。
执行超时和长度限制: 限制命令执行的最长时间和最大命令字符串长度，防止资源滥用。
详细错误报告: 提供清晰的错误信息，帮助开发者诊断和解决问题。
异步操作支持: 支持异步操作，提高服务器的响应性和效率。
工作目录限制: 所有命令都在预设的工作目录下执行，进一步增强安全性。

安装步骤

使用 Smithery 安装 (推荐 Claude Desktop 用户): 如果您使用 Claude Desktop，可以通过 Smithery 自动安装 CLI MCP Server。在终端中运行以下命令：
```
npx @smithery/cli install cli-mcp-server --client claude
```

手动安装 (通用步骤):

克隆仓库: 首先，克隆 GitHub 仓库到本地：

git clone https://github.com/MladenSU/cli-mcp-server.git
cd cli-mcp-server

安装依赖: 使用 'uv' (或 'pip') 安装项目依赖：

uv sync

或者

pip install -r requirements.txt

服务器配置

要将 CLI MCP Server 集成到 MCP 客户端 (例如 Claude Desktop)，您需要配置客户端以连接到此服务器。以下是 Claude Desktop 客户端的配置示例，通常添加到 '~/Library/Application\ Support/Claude/claude_desktop_config.json' 文件中。

开发/未发布服务器配置 (Development/Unpublished Servers Configuration):

{
  "mcpServers": {
    "cli-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "<path/to/the/repo>/cli-mcp-server",  //  替换为您的仓库本地路径
        "run",
        "cli-mcp-server"
      ],
      "env": {
        "ALLOWED_DIR": "</your/desired/dir>",  //  **[必填]** 替换为允许命令执行的根目录的绝对路径，例如 "/home/user/documents"
        "ALLOWED_COMMANDS": "ls,cat,pwd,echo", //  允许执行的命令白名单，逗号分隔，或 "all" 允许所有命令
        "ALLOWED_FLAGS": "-l,-a,--help,--version", // 允许使用的命令选项白名单，逗号分隔，或 "all" 允许所有选项
        "MAX_COMMAND_LENGTH": "1024",        //  最大命令字符串长度
        "COMMAND_TIMEOUT": "30"             //  命令执行超时时间 (秒)
      }
    }
  }
}

发布服务器配置 (Published Servers Configuration):

{
  "mcpServers": {
    "cli-mcp-server": {
      "command": "uvx",
      "args": [
        "cli-mcp-server"
      ],
      "env": {
        "ALLOWED_DIR": "</your/desired/dir>",  //  **[必填]** 替换为允许命令执行的根目录的绝对路径，例如 "/home/user/documents"
        "ALLOWED_COMMANDS": "ls,cat,pwd,echo", //  允许执行的命令白名单，逗号分隔，或 "all" 允许所有命令
        "ALLOWED_FLAGS": "-l,-a,--help,--version", // 允许使用的命令选项白名单，逗号分隔，或 "all" 允许所有选项
        "MAX_COMMAND_LENGTH": "1024",        //  最大命令字符串长度
        "COMMAND_TIMEOUT": "30"             //  命令执行超时时间 (秒)
      }
    }
  }
}

重要配置参数说明:

'ALLOWED_DIR': [必填] 这是最关键的安全配置。请务必将其设置为您希望 LLM 能够访问的目录的绝对路径。所有命令的文件操作都将被限制在此目录及其子目录内。
'ALLOWED_COMMANDS': 配置允许 LLM 执行的命令列表。默认值为 "ls,cat,pwd"。您可以根据需要添加或删除命令。设置为 '"all"' 将允许执行任何命令，但会降低安全性，请谨慎使用。
'ALLOWED_FLAGS': 配置允许与白名单命令一起使用的选项 (flags)。默认值为 "-l,-a,--help"。您可以根据需要添加或删除选项。设置为 '"all"' 将允许使用所有选项，同样请谨慎使用。
'MAX_COMMAND_LENGTH': 限制可以执行的命令字符串的最大长度，防止过长的命令输入。
'COMMAND_TIMEOUT': 设置命令执行的超时时间，单位为秒。如果命令执行时间超过此限制，服务器将终止该命令。

基本使用方法

配置完成后，您的 MCP 客户端 (如 Claude Desktop) 应该能够连接到 CLI MCP Server 并使用其提供的工具。

可用工具:

'run_command': 执行指定的命令行命令。

输入参数:

{
  "command": "要执行的命令字符串，例如 'ls -l' 或 'cat file.txt'"
}

功能描述: 在 'ALLOWED_DIR' 目录下安全地执行白名单中的命令。

'show_security_rules': 显示当前服务器的安全配置规则。
- 输入参数: 无
- 功能描述: 返回服务器当前的安全配置信息，包括允许的目录、命令、选项以及安全限制等。

示例使用场景:

LLM 可以使用 'run_command' 工具来获取服务器上的文件列表 (例如 'ls -l') 或读取文件内容 (例如 'cat report.txt')，前提是这些命令在白名单中，并且操作路径在 'ALLOWED_DIR' 范围内。
LLM 可以调用 'show_security_rules' 工具来了解当前环境的安全配置，从而更好地指导用户进行安全的操作。

安全性提示:

请务必仔细配置 'ALLOWED_DIR'、'ALLOWED_COMMANDS' 和 'ALLOWED_FLAGS'，以确保服务器的安全性。
避免将 'ALLOWED_COMMANDS' 和 'ALLOWED_FLAGS' 设置为 '"all"'，除非您完全信任使用此服务器的 LLM 应用，并清楚了解潜在的安全风险。
定期审查和更新安全配置，以适应不断变化的安全需求。

通过合理配置和使用 CLI MCP Server，您可以安全地为 LLM 应用提供强大的命令行操作能力，同时最大限度地降低安全风险。

关键词