Super Shell MCP 服务器

这是一个用于在多个平台（Windows、macOS 和 Linux）上执行 shell 命令的 MCP（Model Context Protocol）服务器。该服务器提供了一种安全的方式来执行 shell 命令，并内置了白名单和审批机制。

功能

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

安装

通过 Smithery 安装

要通过 Smithery 自动安装适用于 Claude Desktop 的 Super Shell MCP 服务器：

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

手动安装

bash

克隆仓库

git clone https://github.com/cfdude/super-shell-mcp.git
cd super-shell-mcp

安装依赖

npm install

构建项目

npm run build

使用

启动服务器

bash
npm start

或者直接运行：

bash
node build/index.js

在 Roo Code 和 Claude Desktop 中配置

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

选项 1：使用 NPX（推荐）

使用 NPX 是最简单的方式，它会自动从 npm 安装并运行包，而无需手动设置。该包在 NPM 上的地址为 https://www.npmjs.com/package/super-shell-mcp。

使用 NPX 的 Roo Code 配置

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

使用 NPX 的 Claude Desktop 配置

json
"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）：

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

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

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

Windows 11 示例
json
"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）：

json
"super-shell": {
"command": "node",
"args": [
"/path/to/super-shell-mcp/build/index.js"
],
"alwaysAllow": false,
"disabled": false
}对于 Windows 用户，配置文件通常位于 %APPDATA%Claudeclaude_desktop_config.json。

平台特定配置

Windows

• 默认 shell: cmd.exe（如果可用则为 PowerShell）
• 配置路径：
  • Roo Code: %APPDATA%CodeUserglobalStorage ooveterinaryinc.roo-clinesettingscline_mcp_settings.json
  • Claude Desktop: %APPDATA%Claudeclaude_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：

json
"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 的信息。

json
{}

execute_command

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

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

get_whitelist

获取白名单命令列表。

json
{}

add_to_whitelist

将命令添加到白名单。

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

update_security_level

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

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

remove_from_whitelist

从白名单中移除命令。

json
{
"command": "python3"
}

get_pending_commands

获取待批准的命令列表。

json
{}

approve_command

批准一个待批准的命令。

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

deny_command

拒绝一个待批准的命令。

json
{
"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 工具来扩展白名单。例如：

json
{
"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 使用最新的开发版本：

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

发布你自己的版本

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

1. 更新 package.json 中的详细信息

2. 确保 "bin" 字段正确配置：
   json
   "bin": {
   "super-shell-mcp": "./build/index.js"
   }

3. 发布到 npm：
   bash
   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. 发布流程：
   bash

   更新 package.json 中的版本

   npm version patch # 或根据需要使用 minor/major

   构建并发布

   npm publish

这些实践确保了 MCP 服务器可以由 MCP 客户端自动启动，而不需要单独的终端窗口，从而改善用户体验和操作效率。

故障排除

跨平台问题

Windows 特定问题

1. PowerShell 脚本执行策略

   • 问题：PowerShell 可能会因为“此系统上禁止脚本执行”的错误而阻止脚本执行
   • 解决方案：以管理员身份运行 PowerShell 并执行 Set-ExecutionPolicy RemoteSigned，或在配置 shell 时使用 -ExecutionPolicy Bypass 参数

2. 路径分隔符

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

3. 命令未找到

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

macOS/Linux 特定问题

1. Shell 权限

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

2. 环境变量

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

一般故障排除

1. Shell 检测问题

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

2. 命令执行超时

   • 问题：命令执行时间过长导致超时
   • 解决方案：在命令服务构造函数中增加超时值

日志系统

服务器包括一个全面的日志系统，将日志写入文件以便于调试和监控：

1. 日志文件位置

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

2. 日志级别

   • INFO：一般的操作信息
   • DEBUG：详细的调试信息
   • ERROR：错误条件和异常

3. 查看日志

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

     查看整个日志

     cat logs/super-shell-mcp.log

     实时跟踪日志更新

     tail -f logs/super-shell-mcp.log

4. 日志内容

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

5. 白名单管理

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

许可证

此 MCP 服务器依据 MIT 许可证授权。这意味着您可以自由地使用、修改和分发该软件，但需遵守 MIT 许可证的条款和条件。更多详情，请参阅项目仓库中的 LICENSE 文件。