CLI MCP Server 使用说明

项目简介

CLI MCP Server 是一个实现了 Model Context Protocol (MCP) 的服务器，专注于为大型语言模型 (LLM) 提供安全可控的命令行 (CLI) 执行能力。它通过严格的安全措施，如命令白名单、路径验证和执行控制，确保 LLM 在访问本地系统资源时的安全性。

主要功能点

安全命令执行：仅执行在白名单中配置的命令，防止恶意命令注入。
可配置的安全策略：允许配置允许执行的命令、命令参数（flags）、最大命令长度和超时时间。
路径安全：限制命令只能在配置的 'ALLOWED_DIR' 目录及其子目录下操作，防止路径遍历攻击。
防止 Shell 操作符注入：禁用 Shell 操作符，避免复杂的、潜在危险的命令执行。
详细的错误报告：提供清晰的错误信息，帮助开发者和用户理解命令执行失败的原因。
异步操作支持：支持异步操作，提高服务器的响应性能。

安装步骤

环境准备：确保已安装 Python 3.10 或更高版本。

通过 Smithery 安装 (推荐 Claude Desktop 用户使用):

npx @smithery/cli install cli-mcp-server --client claude

此命令会自动安装并配置 CLI MCP Server。

服务器配置

MCP 客户端需要配置服务器的启动信息才能连接和使用 CLI MCP Server。以下是针对 Claude Desktop 的配置示例，你需要将以下 JSON 配置添加到 '~/Library/Application\ Support/Claude/claude_desktop_config.json' 文件中（如果文件不存在则创建）。

开发/未发布服务器配置示例

{
  "mcpServers": {
    "cli-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "<path/to/the/repo>/cli-mcp-server",
        "run",
        "cli-mcp-server"
      ],
      "env": {
        "ALLOWED_DIR": "</your/desired/directory>",
        "ALLOWED_COMMANDS": "ls,cat,pwd",
        "ALLOWED_FLAGS": "-l,-a,--help",
        "MAX_COMMAND_LENGTH": "1024",
        "COMMAND_TIMEOUT": "30"
      }
    }
  }
}

发布服务器配置示例

{
  "mcpServers": {
    "cli-mcp-server": {
      "command": "uvx",
      "args": [
        "cli-mcp-server"
      ],
      "env": {
        "ALLOWED_DIR": "</your/desired/directory>",
        "ALLOWED_COMMANDS": "ls,cat,pwd",
        "ALLOWED_FLAGS": "-l,-a,--help",
        "MAX_COMMAND_LENGTH": "1024",
        "COMMAND_TIMEOUT": "30"
      }
    }
  }
}

配置参数说明：

'"cli-mcp-server"': 服务器名称，在 Claude Desktop 客户端中用于标识和选择该服务器。
'"command"': 启动服务器的命令。'uv' 和 'uvx' 是示例中使用的包管理和运行工具，你需要根据你的实际环境和安装方式进行调整。如果直接使用 Python 运行，可以设置为 'python'。
'"args"': 传递给启动命令的参数列表。
- 对于开发配置，'"--directory"' 指定了服务器代码所在的目录， '"run"' 命令指示 'uv' 运行指定的脚本 'cli-mcp-server'。'<path/to/the/repo>/cli-mcp-server' 需要替换为你的 'cli-mcp-server' 仓库的本地路径。
- 对于发布配置，假设 'cli-mcp-server' 已被打包并可以通过 'uvx' 直接运行，则只需指定 'cli-mcp-server' 作为参数。
'"env"': 环境变量配置，用于配置服务器的安全策略：
- '"ALLOWED_DIR"': (必需) 允许命令执行的基础目录。LLM 只能访问和操作此目录及其子目录下的文件。请替换 '</your/desired/directory>' 为你希望允许 LLM 访问的实际目录路径。
- '"ALLOWED_COMMANDS"': 允许执行的命令白名单，多个命令之间用逗号分隔。例如 '"ls,cat,pwd"'。你可以根据需要添加或修改允许的命令。
- '"ALLOWED_FLAGS"': 允许使用的命令参数（flags）白名单，多个参数之间用逗号分隔。例如 '"-l,-a,--help"'。根据需要配置。
- '"MAX_COMMAND_LENGTH"': 允许的最大命令字符串长度，防止执行过长的命令，默认为 '"1024"'。
- '"COMMAND_TIMEOUT"': 命令执行超时时间，单位为秒，默认为 '"30"' 秒。

重要：请务必根据你的实际需求配置 '"ALLOWED_DIR"'、'"ALLOWED_COMMANDS"' 和 '"ALLOWED_FLAGS"'，以确保安全性和功能性。

基本使用方法

启动 MCP 客户端：例如，启动配置了 CLI MCP Server 的 Claude Desktop 客户端。
在 LLM 中使用工具：在与 LLM 的对话中，你可以指示 LLM 使用 'run_command' 工具执行命令行操作。例如，你可以指示 Claude 执行 'ls -l /your/desired/directory' 命令来列出指定目录的文件。
查看安全规则：你可以指示 LLM 使用 'show_security_rules' 工具来查看当前服务器配置的安全规则，包括允许的命令、参数、工作目录和安全限制等。

示例对话 (与 Claude Desktop)：

用户：请列出 '/tmp' 目录下的所有文件和文件夹。 Claude (可能会调用 'run_command' 工具)：'ls -l /tmp' CLI MCP Server (执行命令后返回结果)：... (文件列表) ...

用户：当前允许哪些命令和参数？ Claude (可能会调用 'show_security_rules' 工具) CLI MCP Server (返回安全规则信息)：... (安全配置信息) ...

通过以上步骤，你就可以在 LLM 应用中使用 CLI MCP Server 提供的安全命令行执行能力了。

关键词