CLI MCP 服务器

一个用于执行受控命令行操作的安全模型上下文协议（MCP）服务器实现，具有全面的安全特性。

目录

1. 概述
2. 特性
3. 配置
4. 可用工具
   • run_command
   • show_security_rules
5. 与Claude桌面版的使用
   • 开发/未发布的服务器配置
   • 已发布服务器的配置
6. 安全特性
7. 错误处理
8. 开发
   • 前提条件
   • 构建和发布
   • 调试
9. 许可

概述

此MCP服务器通过包括命令白名单、路径验证和执行控制在内的强大安全措施，实现了安全的命令行执行。非常适合在保持安全性的同时为LLM应用程序提供受控的CLI访问。

特性

• 🔒 带有严格验证的安全命令执行
• ⚙️ 可配置的命令和标志白名单，支持“all”选项
• 🛡️ 防止路径遍历并进行验证
• 🚫 防止Shell操作符注入
• ⏱️ 执行超时和长度限制
• 📝 详细的错误报告
• 🔄 支持异步操作
• 🎯 工作目录限制和验证

配置

使用环境变量配置服务器：

注意：将ALLOWED_COMMANDS或ALLOWED_FLAGS设置为'all'将允许任何命令或标志。

安装

要通过Smithery自动安装适用于Claude桌面版的CLI MCP服务器，请运行：

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

可用工具

run_command

由于原文档中没有提供run_command的具体内容，翻译保留了标题格式。如果有更多关于run_command的信息需要翻译，请补充相关信息。

在允许的目录内执行白名单中的 CLI 命令。

输入模式：

{
  "command": {
    "type": "string",
    "description": "Single command to execute (e.g., 'ls -l' or 'cat file.txt')"
  }
}

安全注意事项：

• 不支持 Shell 操作符（&&, |, >, >>）
• 除非 ALLOWED_COMMANDS='all'，否则命令必须在白名单中
• 除非 ALLOWED_FLAGS='all'，否则标志必须在白名单中
• 所有路径都必须验证是否在 ALLOWED_DIR 内

show_security_rules

显示当前的安全配置和限制，包括：

• 工作目录
• 允许的命令
• 允许的标志
• 安全限制（最大命令长度和超时时间）

在 Claude Desktop 中使用

将以下内容添加到您的 ~/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/dir>",
        "ALLOWED_COMMANDS": "ls,cat,pwd,echo",
        "ALLOWED_FLAGS": "-l,-a,--help,--version",
        "MAX_COMMAND_LENGTH": "1024",
        "COMMAND_TIMEOUT": "30"
      }
    }
  }
}

发布的服务器配置

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

如果不起作用或未在 UI 中显示，请通过 uv clean 清除缓存。

安全特性

• ✅ 命令白名单强制执行，并提供 'all' 选项
• ✅ 标志验证，并提供 'all' 选项
• ✅ 防止路径遍历并进行规范化
• ✅ 阻止 Shell 操作符
• ✅ 命令长度限制
• ✅ 执行超时
• ✅ 工作目录限制
• ✅ 符号链接解析和验证

错误处理

服务器为以下情况提供了详细的错误信息：

• 安全违规（CommandSecurityError）
• 命令超时（CommandTimeoutError）
• 无效的命令格式
• 路径安全违规
• 执行失败（CommandExecutionError）
• 一般命令错误（CommandError）

开发

前提条件

• Python 3.10+
• MCP 协议库

构建和发布

准备分发包：

1. 同步依赖项并更新锁文件：

   uv sync
   

2. 构建包分发：

   uv build
   

   这将在 dist/ 目录中创建源码和 wheel 分发包。

3. 发布到 PyPI：

   uv publish --token {{YOUR_PYPI_API_TOKEN}}
   

调试

由于 MCP 服务器通过 stdio 运行，调试可能会很困难。为了获得最佳调试体验，我们强烈建议使用 MCP Inspector。

您可以使用 npm 通过以下命令启动 MCP Inspector：

npx @modelcontextprotocol/inspector uv --directory {{your source code local directory}}/cli-mcp-server run cli-mcp-server

启动后，Inspector 将显示一个 URL，您可以在浏览器中访问该 URL 以开始调试。

许可证

本项目根据 MIT 许可证许可 - 有关详细信息，请参阅 LICENSE 文件。

如需更多信息或支持，请在项目仓库中打开一个问题。