CLI MCP 服务器

---

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

---

目录

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

---

概述

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

特性

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

配置

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

变量	描述	默认值
ALLOWED_DIR	命令执行的基础目录（必需）	无（必需）
ALLOWED_COMMANDS	允许的命令列表，以逗号分隔，或 'all'	ls,cat,pwd
ALLOWED_FLAGS	允许的标志列表，以逗号分隔，或 'all'	-l,-a,--help
MAX_COMMAND_LENGTH	命令字符串的最大长度	1024
COMMAND_TIMEOUT	命令执行超时时间（秒）	30
ALLOW_SHELL_OPERATORS	允许 Shell 操作符（&&, ||, |, > 等）	false

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

安装

通过 Smithery 自动为 Claude Desktop 安装 CLI MCP 服务器：

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

可用工具

run_command

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

输入模式：

{
  "command": {
    "type": "string",
    "description": "要执行的单个命令（例如 'ls -l' 或 'cat file.txt'）"
  }
}

安全说明：

• 默认不支持 Shell 操作符（&&, |, >, >>），但可以通过 ALLOW_SHELL_OPERATORS=true 启用
• 命令必须在白名单中，除非 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",
        "ALLOW_SHELL_OPERATORS": "false"
      }
    }
  }
}

已发布服务器配置

{
  "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",
        "ALLOW_SHELL_OPERATORS": "false"
      }
    }
  }
}

如果无法工作或在 UI 中不显示，请通过 uv clean 清除缓存。

安全特性

• ✅ 命令白名单强制执行，支持 'all' 选项
• ✅ 标志验证，支持 'all' 选项
• ✅ 防止路径遍历并进行规范化
• ✅ 阻止 Shell 操作符（可通过 ALLOW_SHELL_OPERATORS=true 选择启用）
• ✅ 命令长度限制
• ✅ 执行超时
• ✅ 工作目录限制
• ✅ 符号链接解析和验证

错误处理

服务器提供详细的错误信息，包括：

• 安全违规（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 检查器。

您可以通过 npm 使用以下命令启动 MCP 检查器：

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

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

许可证

本项目根据 MIT 许可证授权 - 详情请参阅 LICENSE 文件。

---

如需更多信息或支持，请在项目仓库中提交问题。