超级 Shell MCP 服务器

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

特征

• 在 Windows、macOS 和 Linux 上通过 MCP 执行 shell 命令

• 自动平台检测和 shell 选择

• 支持多个 shell：

  • Windows ：cmd.exe、PowerShell

  • macOS ：zsh、bash、sh

  • Linux ：bash、sh、zsh

• 具有安全级别的命令白名单：

  • 安全：无需批准即可执行的命令

  • 需要批准：执行前需要明确批准的命令

  • 禁止：明确阻止的命令

• 特定于平台的命令白名单

• 针对潜在危险命令的非阻塞审批工作流程

• 具有基于文件的日志的综合日志系统

• 全面的命令管理工具

• 用于诊断的平台信息工具

安装

通过 Smithery 安装

要通过Smithery自动为 Claude Desktop 安装 Super Shell MCP Server：

手动安装

用法

启动服务器

或者直接：

在 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 代码配置

使用 NPX 配置 Claude 桌面

选项 2：使用本地安装

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

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

Windows 11 示例

Claude桌面配置

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

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

平台特定配置

视窗

• 默认 shell：cmd.exe（或 PowerShell，如果可用）

• 配置路径：

  • Roo 代码： %APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json

  • 克劳德桌面： %APPDATA%\Claude\claude_desktop_config.json

• Shell 路径示例：

  • cmd.exe： C:\\Windows\\System32\\cmd.exe

  • PowerShell： C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe

  • PowerShell 核心： C:\\Program Files\\PowerShell\\7\\pwsh.exe

macOS

• 默认 shell：/bin/zsh

• 配置路径：

  • Roo 代码： ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json

  • Claude 桌面： ~/Library/Application Support/Claude/claude_desktop_config.json

• Shell 路径示例：

  • zsh： /bin/zsh

  • 庆典： /bin/bash

  • sh： /bin/sh

Linux

• 默认 shell：/bin/bash（或 $SHELL 环境变量）

• 配置路径：

  • Roo 代码： ~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json

  • 克劳德桌面： ~/.config/Claude/claude_desktop_config.json

• Shell 路径示例：

  • 庆典： /bin/bash

  • sh： /bin/sh

  • zsh： /usr/bin/zsh

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

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

笔记：

• 对于 Roo 代码：出于安全考虑，建议将alwaysAllow设置为空数组[] ，因为它会在执行任何命令之前提示您批准。如果您想允许特定命令而不提示，可以将这些命令的名称添加到数组中，例如： "alwaysAllow": ["execute_command", "get_whitelist"] 。

• 对于 Claude Desktop：出于安全考虑，建议alwaysAllow设置为false Desktop 使用布尔值而不是数组，其中false表示所有命令都需要批准， true表示所有命令均允许，无需提示。

重要提示： alwaysAllow参数由 MCP 客户端（Roo Code 或 Claude Desktop）处理，而非 Super Shell MCP 服务器本身。服务器无论使用哪种格式都能正常工作，因为客户端会在向服务器发送请求之前处理审批流程。

可用工具

该服务器公开以下 MCP 工具：

get_platform_info

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

execute_command

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

get_whitelist

获取白名单命令列表。

add_to_whitelist

将命令添加到白名单。

update_security_level

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

remove_from_whitelist

从白名单中删除命令。

get_pending_commands

获取待批准的命令列表。

approve_command

批准待处理的命令。

deny_command

拒绝待处理的命令。

默认白名单命令

该服务器包括根据检测到的平台自动选择的平台特定的命令白名单。

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

• 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工具扩展白名单。例如：

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

发布您自己的版本

如果你想将自己修改的版本发布到 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. 出版流程：

   # Update version in package.json npm version patch # or minor/major as appropriate # Build and publish 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

   • 日志目录由 Git 自动创建并跟踪（使用 .gitkeep 文件）

   • 日志文件本身通过 .gitignore 从 Git 中排除

   • 包含有关服务器操作、命令执行和审批工作流程的详细信息

2. 日志级别

   • INFO ：一般操作信息

   • DEBUG ：详细的调试信息

   • ERROR ：错误条件和异常

3. 查看日志

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

     # View the entire log cat logs/super-shell-mcp.log # Follow log updates in real-time tail -f logs/super-shell-mcp.log

4. 日志内容

   • 服务器启动和配置

   • 命令执行请求和结果

   • 批准工作流事件（待定、已批准、已拒绝）

   • 错误情况和故障排除信息

5. 白名单管理

   • 问题：需要将自定义命令添加到白名单

   • 解决方案：使用add_to_whitelist工具添加特定于您的环境的命令

执照

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