CLI MCP Server

CLI MCP Server

---

一种安全的 Model Context Protocol（MCP）服务实现，可执行受控的命令行操作，并提供全面的安全功能。

---

目录

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

---

概览

此 MCP 服务支持安全地执行命令行操作，并提供强大的安全措施，包括命令白名单、路径验证和执行控制。非常适合为大模型应用提供受控的 CLI 访问，同时确保安全性。

功能

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

配置

使用环境变量配置服务：

变量	描述	默认值
ALLOWED_DIR	命令执行的基础目录（必填）	None（必填）
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 Server：

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

可用工具

run_command

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

输入架构：

{
  "command": {
    "type": "string",
    "description": "Single command to execute (e.g., 'ls -l' or '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"
      }
    }
  }
}

如果无法正常工作或未显示在界面中，请运行 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 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 授权，详情请参阅 LICENSE 文件。

---

如需了解更多信息或获得支持，请在项目仓库中提交 issue。