Super Shell MCP Server

](https://mseep.ai/app/cfdude-super-shell-mcp)

超级外壳MCP服务器

](https://smithery.ai/package/@cfdude/super-shell-mcp)

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

🎉 现在可作为Claude桌面扩展程序使用！ 使用单击安装 .dxt 软件包-无需开发工具或配置。

特性

• 在Windows、macOS和Linux上通过MCP执行shell命令
• 自动平台检测和外壳选择
• 支持多个shell：

- 视窗：cmd.exe，PowerShell - macOS：zsh、bash、sh - Linux：bash、sh、zsh

• 默认情况下禁用Shell解析以消除命令注入风险，并为受信任的工作流提供明确的选择加入模式
• 具有安全级别的命令白名单：

- 安全：未经批准即可执行的命令 - 需要批准：执行前需要明确批准的命令 - 禁止：明确阻止的命令

• 特定于平台的命令白名单
• 潜在危险命令的非阻塞审批工作流
• 基于文件的日志综合记录系统
• 全面的指挥管理工具
• 用于诊断的平台信息工具

安装

选项1:克劳德桌面扩展（.dxt）-推荐

Claude Desktop的一键安装：

1. 下载 这 super-shell-mcp.dxt 文件来自 最新版本

1. 快速安装：双击 .dxt Claude Desktop打开时的文件

或

手动安装:

- 打开克劳德桌面 - 首选 设置 > 扩展 - 点击 “添加扩展名” - 选择已下载的 super-shell-mcp.dxt 文件

1. 配置 （可选）：如果需要，设置自定义shell路径

1. 开始使用 -该扩展已准备好立即使用！

✅ DXT安装的好处：

• 无需开发工具（Node.js、Python等）
• 无手动配置文件
• 自动依赖关系管理
• 一键安装和更新
• 操作系统密钥链中的安全凭据存储

选项2：通过Smithery安装

通过以下方式自动安装Claude Desktop的Super Shell MCP服务器 史密瑟里:

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

选项3：手动安装

# Clone the repository
git clone https://github.com/cfdude/super-shell-mcp.git
cd super-shell-mcp

# Install dependencies
npm install

# Build the project
npm run build

用法

适用于Claude桌面扩展用户（.dxt）

如果您使用 .dxt 扩展（选项1）， 你准备好了！ 无需额外配置。扩展程序会自动处理所有事情：

• ✅ 自动启动 当Claude Desktop启动时
• ✅ 平台检测 以及适当的外壳选择
• ✅ 内置安全 具有命令白名单和审批工作流
• ✅ 可选配置 通过Claude Desktop的扩展设置

对于手动安装用户

如果您手动安装（选项2或3），则需要配置Claude Desktop或MCP客户端：

手动启动服务器

npm start

或者直接：

node build/index.js

MCP客户端的手动配置

对于手动安装，Roo Code和Claude Desktop都对MCP服务器使用类似的配置格式：

使用NPX（建议手动设置）

使用Super Shell MCP最简单的方法是使用NPX，它可以自动从npm安装和运行包，而不需要手动设置。该套餐可在NPM上购买，网址为 .

使用NPX配置Roo代码

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

使用NPX进行Claude桌面配置

"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"
  ],
  "env": {
    "CUSTOM_SHELL": "/usr/bin/bash",
    "SUPER_SHELL_USE_SHELL": "true"
  },
  "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"
  ],
  "env": {
    "CUSTOM_SHELL": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
    "SUPER_SHELL_USE_SHELL": "true"
  },
  "alwaysAllow": [],
  "disabled": false
}

Claude桌面配置

将以下内容添加到您的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.

平台特定配置

视窗

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

- 房间代码： %APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json - 克劳德桌面： %APPDATA%\Claude\claude_desktop_config.json

• 外壳路径示例：

- 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
• 配置路径：

- 房间代码： ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json - 克劳德桌面： ~/Library/Application Support/Claude/claude_desktop_config.json

• 外壳路径示例：

- zsh： /bin/zsh - 猛击： /bin/bash - sh： /bin/sh

Linux

• 默认shell：/bin/bash（或$shell环境变量）
• 配置路径：

- 房间代码： ~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json - 克劳德桌面： ~/.config/Claude/claude_desktop_config.json

• 外壳路径示例：

- 猛击： /bin/bash - sh： /bin/sh - zsh： /usr/bin/zsh

Shell执行模式和环境变量

Shell解析是 默认禁用 为了安全。使用以下环境变量自定义行为：

• SUPER_SHELL_USE_SHELL：设置为 true （或 1/yes/on)为受信任的工作流启用shell解析。省略或设置为 false 以保持更安全的默认值。
• CUSTOM_SHELL：启用shell解析时使用的shell可执行文件的可选路径。
• SUPER_SHELL_COMMAND_TIMEOUT：默认30秒命令超时的可选覆盖（毫秒）。

⚠️ 启用shell解析会重新引入命令注入的风险。仅当您完全信任命令源和有效负载时才启用它。

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

备注: - Roo代码：设置 alwaysAllow 变为空数组 [] 出于安全原因，建议使用，因为它会在执行任何命令之前提示批准。如果你想在不提示的情况下允许特定命令，你可以将它们的名称添加到数组中，例如： "alwaysAllow": ["execute_command", "get_whitelist"]. - 克劳德桌面：设置 alwaysAllow 到 false 出于安全原因，建议使用。Claude Desktop使用布尔值而不是数组，其中 false 意味着所有命令都需要批准，以及 true 意味着所有命令都是允许的，没有提示。 重要：The 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": "Run Python 3 scripts"
}

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": "This command is potentially dangerous"
}

默认白名单命令

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

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

• 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 防止外壳注射
• 指定时，根据允许的模式验证参数

扩大白名单

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

{
  "command": "npm",
  "securityLevel": "requires_approval",
  "description": "Node.js package manager"
}

NPM包信息

Super Shell MCP可作为npm包在 .

使用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": [],  // For Roo Code
  "disabled": false
}

发布自己的版本

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

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

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

1. 发布到npm：

   npm publish

NPX最佳实践

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

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

1. 软件包配置:

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

1. TypeScript配置:

- "module": "NodeNext" -适当的ES模块支持 - "moduleResolution": "NodeNext" -与ES模块一致

1. 自动安装和执行:

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

1. 出版流程:

   # 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 或使用 -ExecutionPolicy Bypass 配置shell时的参数

1. 路径分隔符

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

1. 未找到命令

- 问题：Windows没有像这样的Unix命令 ls, grep等等。 - 解决方案：使用Windows等效工具(dir 而不是 ls, findstr 而不是 grep)

macOS/Linux特定问题

1. Shell权限

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

1. 环境变量

- 问题：MCP服务器中没有环境变量 - 解决方案：在shell的配置文件中设置环境变量(.zshrc, .bashrc等等）

一般故障排除

1. 外壳检测问题

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

1. 命令执行超时

- 问题：命令耗时过长且超时 - 解决方案：增加命令服务构造函数中的超时值

记录系统

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

1. 日志文件位置

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

1. 日志级别

- 信息：一般操作信息 - 调试：详细的调试信息 - 错误：错误条件和异常

1. 查看日志

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

     # View the entire log
     cat logs/super-shell-mcp.log

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

1. 日志内容

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

1. 白名单管理

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

已知问题

安卓工作室水獭2功能下降兼容性

受影响的版本：安卓工作室水獭2功能下降| 2025.2.2金丝雀3（内部版本号AI-252.25557.131.2522.14357309）

问题：Android Studio的MCP客户端实现在调用时将数组参数错误地序列化为字符串 execute_command 工具。这会导致带有参数的命令失败，并出现错误：

Error: Expected array, received string

示例:

// This fails in Android Studio Otter 2
execute_command(
  command = "git",
  args = ["add", "."]  // Sent as string '["add", "."]' instead of array
)

根本原因：这是Android Studio的MCP客户端中的错误，而不是超级shell MCP中的错误。服务器正确定义 args 作为类型 array 在其模式中，该问题已被验证可以正常工作：

• 克劳德桌面
• 官方MCP SDK客户端
• 其他MCP兼容工具

状态：这是一个Android Studio错误。超级shell mcp服务器正确实现了mcp规范。

变通方案：目前没有可用的。遇到此问题的用户应向Android Studio/JetBrains团队报告。

参考文献:

• 报告的问题： #20
• 相关文件： Android Studio Gemini MCP集成

许可证

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