Super Shell MCP 服务器

一个用于在多个平台（Windows、macOS、Linux）上执行 shell 命令的 MCP（模型上下文协议）服务器。该服务器提供了一种安全的方式来执行 shell 命令，具有内置的白名单和审批机制。

特性

• 通过 MCP 在 Windows、macOS 和 Linux 上执行 shell 命令
• 自动平台检测和 shell 选择
• 支持多种 shell：
  • Windows: cmd.exe, PowerShell
  • macOS: zsh, bash, sh
  • Linux: bash, sh, zsh
• 具有安全级别的命令白名单：
  • Safe (安全): 无需审批即可执行的命令
  • Requires Approval (需要审批): 执行前需要明确批准的命令
  • Forbidden (禁止): 明确阻止的命令
• 平台特定的命令白名单
• 用于潜在危险命令的非阻塞审批工作流程
• 具有基于文件的日志的综合日志记录系统
• 综合命令管理工具
• 用于诊断的平台信息工具

安装

通过 Smithery 安装

要通过 Smithery 为 Claude Desktop 自动安装 Super Shell MCP 服务器：

npx -y @smithery/cli install @cfdude/super-shell-mcp --client claude

手动安装

# 克隆仓库
git clone https://github.com/cfdude/super-shell-mcp.git
cd super-shell-mcp

# 安装依赖
npm install

# 构建项目
npm run build

使用

启动服务器

npm start

或者直接：

node build/index.js

在 Roo Code 和 Claude Desktop 中配置

Roo Code 和 Claude Desktop 都使用类似的 MCP 服务器配置格式。以下是如何设置 Super Shell MCP 服务器：

选项 1：使用 NPX（推荐）

使用 Super Shell MCP 的最简单方法是使用 NPX，它可以自动从 npm 安装和运行软件包，而无需手动设置。该软件包可在 NPM 上找到：https://www.npmjs.com/package/super-shell-mcp。

使用 NPX 的 Roo Code 配置

"super-shell": {
  "command": "npx",
  "args": [
    "-y",
    "super-shell-mcp"
  ],
  "alwaysAllow": [],
  "disabled": false
}

使用 NPX 的 Claude Desktop 配置

"super-shell": {
  "command": "npx",
  "args": [
    "-y",
    "super-shell-mcp"
  ],
  "alwaysAllow": false,
  "disabled": false
}

选项 2：使用本地安装

如果您更喜欢使用本地安装，请将以下内容添加到您的 Roo Code MCP 设置配置文件（位于 ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json）：

"super-shell": {
  "command": "node",
  "args": [
    "/path/to/super-shell-mcp/build/index.js"
  ],
  "alwaysAllow": [],
  "disabled": false
}

您可以选择通过添加 shell 参数来指定自定义 shell：

"super-shell": {
  "command": "node",
  "args": [
    "/path/to/super-shell-mcp/build/index.js",
    "--shell=/usr/bin/bash"
  ],
  "alwaysAllow": [],
  "disabled": false
}

Windows 11 示例

"super-shell": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "C:\\Program Files\\nodejs\\node_modules\\npm\\bin\\npx-cli.js",
        "-y",
        "super-shell-mcp",
        "C:\\Users\\username"
      ],
      "alwaysAllow": [],
      "disabled": false
    }

Claude Desktop 配置

将以下内容添加到您的 Claude Desktop 配置文件（位于 ~/Library/Application Support/Claude/claude_desktop_config.json）：

"super-shell": {
  "command": "node",
  "args": [
    "/path/to/super-shell-mcp/build/index.js"
  ],
  "alwaysAllow": false,
  "disabled": false
}

对于 Windows 用户，配置文件通常位于 %APPDATA%\Claude\claude_desktop_config.json。

平台特定配置

Windows

• 默认 shell: cmd.exe (或者 PowerShell，如果可用)
• 配置文件路径:
  • Roo Code: %APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json
  • Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json
• Shell 路径示例:
  • cmd.exe: C:\\Windows\\System32\\cmd.exe
  • PowerShell: C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe
  • PowerShell Core: C:\\Program Files\\PowerShell\\7\\pwsh.exe

macOS

• 默认 shell: /bin/zsh
• 配置文件路径:
  • Roo Code: ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json
  • Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• Shell 路径示例:
  • zsh: /bin/zsh
  • bash: /bin/bash
  • sh: /bin/sh

Linux

• 默认 shell: /bin/bash (或者 $SHELL 环境变量)
• 配置文件路径:
  • Roo Code: ~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json
  • Claude Desktop: ~/.config/Claude/claude_desktop_config.json
• Shell 路径示例:
  • bash: /bin/bash
  • sh: /bin/sh
  • zsh: /usr/bin/zsh

您可以选择指定自定义 shell：

"super-shell": {
  "command": "node",
  "args": [
    "/path/to/super-shell-mcp/build/index.js",
    "--shell=C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe"
  ],
  "alwaysAllow": false,
  "disabled": false
}

将 /path/to/super-shell-mcp 替换为您克隆仓库的实际路径。

注意:

• 对于 Roo Code：建议出于安全原因将 alwaysAllow 设置为空数组 []，因为它会在执行任何命令之前提示批准。 如果您想允许特定命令而不提示，您可以将它们的名称添加到数组中，例如："alwaysAllow": ["execute_command", "get_whitelist"]。
• 对于 Claude Desktop：建议出于安全原因将 alwaysAllow 设置为 false。 Claude Desktop 使用布尔值而不是数组，其中 false 表示所有命令都需要批准，而 true 表示允许所有命令而无需提示。

重要: alwaysAllow 参数由 MCP 客户端（Roo Code 或 Claude Desktop）处理，而不是由 Super Shell MCP 服务器本身处理。 服务器可以正确处理任何格式，因为客户端在将请求发送到服务器之前处理审批过程。

可用工具

服务器公开以下 MCP 工具：

get_platform_info

获取有关当前平台和 shell 的信息。

{}

execute_command

在当前平台上执行 shell 命令。

{
  "command": "ls",
  "args": ["-la"]
}

get_whitelist

获取白名单命令列表。

{}

add_to_whitelist

将命令添加到白名单。

{
  "command": "python3",
  "securityLevel": "safe",
  "description": "运行 Python 3 脚本"
}

update_security_level

更新白名单命令的安全级别。

{
  "command": "python3",
  "securityLevel": "requires_approval"
}

remove_from_whitelist

从白名单中删除命令。

{
  "command": "python3"
}

get_pending_commands

获取待批准的命令列表。

{}

approve_command

批准待处理的命令。

{
  "commandId": "command-uuid-here"
}

deny_command

拒绝待处理的命令。

{
  "commandId": "command-uuid-here",
  "reason": "此命令可能很危险"
}

默认白名单命令

服务器包含特定于平台的命令白名单，这些白名单会根据检测到的平台自动选择。

常用安全命令（所有平台）

• echo - 将文本打印到标准输出

类 Unix 安全命令 (macOS/Linux)

• ls - 列出目录内容
• pwd - 打印工作目录
• echo - 将文本打印到标准输出
• cat - 连接并打印文件
• grep - 在文件中搜索模式
• find - 在目录层次结构中查找文件
• cd - 更改目录
• head - 输出文件的第一部分
• tail - 输出文件的最后一部分
• wc - 打印换行符、单词和字节数

Windows 特定安全命令

• dir - 列出目录内容
• type - 显示文本文件的内容
• findstr - 在文件中搜索字符串
• where - 查找程序
• whoami - 显示当前用户
• hostname - 显示计算机名称
• ver - 显示操作系统版本

需要审批的命令

Windows 需要审批的命令

• copy - 复制文件
• move - 移动文件
• mkdir - 创建目录
• rmdir - 删除目录
• rename - 重命名文件
• attrib - 更改文件属性

Unix 需要审批的命令

• mv - 移动（重命名）文件
• cp - 复制文件和目录
• mkdir - 创建目录
• touch - 更改文件时间戳或创建空文件
• chmod - 更改文件模式位
• chown - 更改文件所有者和组

禁止的命令

Windows 禁止的命令

• del - 删除文件
• erase - 删除文件
• format - 格式化磁盘
• runas - 以另一个用户身份执行程序

Unix 禁止的命令

• rm - 删除文件或目录
• sudo - 以另一个用户身份执行命令

安全注意事项

• 所有命令都以运行 MCP 服务器的用户的权限执行
• 需要审批的命令保存在队列中，直到明确批准
• 永远不会执行禁止的命令
• 服务器使用 Node.js 的 execFile 而不是 exec 来防止 shell 注入
• 参数在指定时会根据允许的模式进行验证

扩展白名单

您可以使用 add_to_whitelist 工具扩展白名单。 例如：

{
  "command": "npm",
  "securityLevel": "requires_approval",
  "description": "Node.js 包管理器"
}

NPM 包信息

Super Shell MCP 可以作为 npm 包在 https://www.npmjs.com/package/super-shell-mcp 上找到。

使用 NPX 的好处

使用 NPX 方法（如配置部分的选项 1 所示）具有以下几个优点：

1. 无需手动设置：无需克隆仓库、安装依赖项或构建项目
2. 自动更新：始终使用最新发布的版本
3. 跨平台兼容性：在 Windows、macOS 和 Linux 上的工作方式相同
4. 简化配置：更短的配置，没有绝对路径
5. 减少维护：没有要管理或更新的本地文件

从 GitHub 使用

如果您更喜欢直接从 GitHub 使用最新的开发版本：

"super-shell": {
  "command": "npx",
  "args": [
    "-y",
    "github:cfdude/super-shell-mcp"
  ],
  "alwaysAllow": [],  // 对于 Roo Code
  "disabled": false
}

发布您自己的版本

如果您想将您自己的修改版本发布到 npm：

1. 使用您的详细信息更新 package.json
2. 确保正确配置了“bin”字段：

   "bin": {
     "super-shell-mcp": "./build/index.js"
   }
   

3. 发布到 npm：

   npm publish
   

NPX 最佳实践

为了与使用 NPX 的 MCP 客户端实现最佳集成，本项目遵循以下最佳实践：

1. 可执行入口点：主文件包含 shebang 行 (#!/usr/bin/env node) 并在构建期间使其可执行。

2. 包配置：

   • "type": "module" - 确保使用 ES 模块
   • "bin" 字段 - 将命令名称映射到入口点
   • "files" 字段 - 指定发布时要包含的文件
   • "prepare" 脚本 - 确保在安装时进行编译

3. TypeScript 配置：

   • "module": "NodeNext" - 正确的 ES 模块支持
   • "moduleResolution": "NodeNext" - 与 ES 模块一致

4. 自动安装和执行：

   • MCP 客户端配置使用 npx -y 自动安装和运行包
   • 没有终端窗口被占用，因为该进程在后台运行

5. 发布过程：

   # 更新 package.json 中的版本
   npm version patch  # 或根据需要使用 minor/major
   
   # 构建和发布
   npm publish
   

这些实践确保 MCP 客户端可以自动启动 MCP 服务器，而无需单独的终端窗口，从而提高用户体验和运营效率。

故障排除

跨平台问题

Windows 特定问题

1. PowerShell 脚本执行策略

   • 问题：PowerShell 可能会阻止脚本执行，并显示错误“Execution of scripts is disabled on this system”
   • 解决方案：以管理员身份运行 PowerShell 并执行 Set-ExecutionPolicy RemoteSigned 或在配置 shell 时使用 -ExecutionPolicy Bypass 参数

2. 路径分隔符

   • 问题：Windows 在路径中使用反斜杠 (\)，需要在 JSON 中转义
   • 解决方案：在 JSON 配置文件中使用双反斜杠 (\\)，例如 C:\\Windows\\System32\\cmd.exe

3. 找不到命令

   • 问题：Windows 没有 Unix 命令，例如 ls、grep 等。
   • 解决方案：使用 Windows 等效命令（dir 代替 ls，findstr 代替 grep）

macOS/Linux 特定问题

1. Shell 权限

   • 问题：执行命令时权限被拒绝
   • 解决方案：确保 shell 具有适当的权限，使用 chmod +x /path/to/shell

2. 环境变量

   • 问题：环境变量在 MCP 服务器中不可用
   • 解决方案：在 shell 的配置文件（.zshrc、.bashrc 等）中设置环境变量

常规故障排除

1. Shell 检测问题

   • 问题：服务器无法检测到正确的 shell
   • 解决方案：在配置中显式指定 shell 路径

2. 命令执行超时

   • 问题：命令花费的时间太长并超时
   • 解决方案：增加命令服务构造函数中的超时值

日志记录系统

服务器包含一个综合日志记录系统，该系统将日志写入文件，以便于调试和监控：

1. 日志文件位置

   • 默认：服务器目录中的 logs/super-shell-mcp.log
   • 日志目录会自动创建并由 Git 跟踪（带有 .gitkeep 文件）
   • 日志文件本身通过 .gitignore 从 Git 中排除
   • 包含有关服务器操作、命令执行和审批工作流程的详细信息

2. 日志级别

   • INFO：常规操作信息
   • DEBUG：详细调试信息
   • ERROR：错误情况和异常

3. 查看日志

   • 使用标准文件查看命令来检查日志：

     # 查看整个日志
     cat logs/super-shell-mcp.log
     
     # 实时跟踪日志更新
     tail -f logs/super-shell-mcp.log
     

4. 日志内容

   • 服务器启动和配置
   • 命令执行请求和结果
   • 审批工作流程事件（待处理、已批准、已拒绝）
   • 错误情况和故障排除信息

5. 白名单管理

   • 问题：需要将自定义命令添加到白名单
   • 解决方案：使用 add_to_whitelist 工具添加特定于您的环境的命令

许可证

此 MCP 服务器已获得 MIT 许可证的许可。 这意味着您可以自由使用、修改和分发该软件，但须遵守 MIT 许可证的条款和条件。 有关更多详细信息，请参阅项目存储库中的 LICENSE 文件。