使用说明

超级外壳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的一键安装：

下载这 super-shell-mcp.dxt 文件来自最新版本
快速安装：双击 .dxt Claude Desktop打开时的文件

或

手动安装:
- 打开克劳德桌面
- 首选设置 > 扩展
- 点击 “添加扩展名”
- 选择已下载的 super-shell-mcp.dxt 文件
配置（可选）：如果需要，设置自定义shell路径
开始使用 -该扩展已准备好立即使用！

✅ 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上购买，网址为 https://www.npmjs.com/package/super-shell-mcp.

使用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包在 https://www.npmjs.com/package/super-shell-mcp.

使用NPX的好处

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

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

使用GitHub

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

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

发布自己的版本

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

用您的详细信息更新package.json

确保“bin”字段配置正确：

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

发布到npm：
```
npm publish
```

NPX最佳实践

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

可执行入口点：主文件包含一行shebang(#!/usr/bin/env node)并且在构建期间可执行。
软件包配置:
- "type": "module" -确保使用ES模块
- "bin" field-将命令名称映射到入口点
- "files" 字段-指定发布时要包含哪些文件
- "prepare" script-确保在安装时进行编译
TypeScript配置:
- "module": "NodeNext" -适当的ES模块支持
- "moduleResolution": "NodeNext" -与ES模块一致
自动安装和执行:
- MCP客户端配置使用 npx -y 自动安装并运行该软件包
- 进程在后台运行时，没有终端窗口被占用

出版流程:

# Update version in package.json
npm version patch  # or minor/major as appropriate

# Build and publish
npm publish

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

故障排除

跨平台问题

Windows特定问题

PowerShell脚本执行策略
- 问题：PowerShell可能会阻止脚本执行，并显示错误“此系统上已禁用脚本执行”
- 解决方案：以管理员身份运行PowerShell并执行 Set-ExecutionPolicy RemoteSigned 或使用 -ExecutionPolicy Bypass 配置shell时的参数
路径分隔符
- 问题：Windows使用反斜杠(\)在路径中，需要用JSON转义
- 解决方案：使用双反睫毛(\\)在JSON配置文件中。， C:\\Windows\\System32\\cmd.exe
未找到命令
- 问题：Windows没有像这样的Unix命令 ls, grep等等。
- 解决方案：使用Windows等效工具(dir 而不是 ls, findstr 而不是 grep)

macOS/Linux特定问题

Shell权限
- 问题：执行命令时权限被拒绝
- 解决方案：确保shell具有适当的权限 chmod +x /path/to/shell
环境变量
- 问题：MCP服务器中没有环境变量
- 解决方案：在shell的配置文件中设置环境变量(.zshrc, .bashrc等等）

一般故障排除

外壳检测问题
- 问题：服务器无法检测到正确的shell
- 解决方案：在配置中明确指定shell路径
命令执行超时
- 问题：命令耗时过长且超时
- 解决方案：增加命令服务构造函数中的超时值

记录系统

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

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

查看日志

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

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

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

日志内容
- 服务器启动和配置
- 命令执行请求和结果
- 审批工作流事件（待定、批准、拒绝）
- 错误情况和故障排除信息
白名单管理
- 问题：需要将自定义命令添加到白名单
- 解决方案：使用 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文件。