超级壳-MCP

Name: 超级壳-MCP
Author: cfdude

作者：cfdude10 星标更新：2025-11-12

安装使用来源：spider==github.com

项目介绍

超级 Shell MCP 服务器

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

🎉 现在可以作为 Claude Desktop 扩展使用！ 使用 .dxt 包一键安装 - 不需要开发者工具或配置。

功能

在 Windows、macOS 和 Linux 上通过 MCP 执行 shell 命令
自动检测平台并选择合适的 shell
支持多种 shell：
- Windows: cmd.exe, PowerShell
- macOS: zsh, bash, sh
- Linux: bash, sh, zsh
默认禁用 shell 解析以消除命令注入风险，对于可信的工作流有明确的启用模式
带有安全级别的命令白名单：
- 安全: 可以在无需批准的情况下执行的命令
- 需要批准: 需要显式批准才能执行的命令
- 禁止: 显式阻止的命令
平台特定的命令白名单
对潜在危险命令的非阻塞审批工作流
全面的日志系统，基于文件的日志
全面的命令管理工具
诊断用的平台信息工具

安装

方案 1: Claude Desktop 扩展 (.dxt) - 推荐

Claude Desktop 的一键安装：

下载 super-shell-mcp.dxt 文件从最新发布
快速安装: 在打开 Claude Desktop 的情况下双击 .dxt 文件

或者

手动安装:
- 打开 Claude Desktop
- 进入设置 > 扩展
- 点击 “添加扩展”
- 选择已下载的 super-shell-mcp.dxt 文件
配置 (可选): 如需自定义 shell 路径，请进行设置
开始使用 - 扩展立即可用！

✅ DXT 安装的好处:

不需要开发者工具 (Node.js, Python 等)
没有手动配置文件
自动依赖管理
一键安装和更新
安全凭证存储在操作系统密钥链中

方案 2: 通过 Smithery 安装

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

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

方案 3: 手动安装

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

# 安装依赖
npm install

# 构建项目
npm run build

使用

对于 Claude Desktop 扩展用户 (.dxt)

如果你使用的是 .dxt 扩展 (方案 1)，你已经准备好使用了！ 不需要额外配置。扩展会自动处理一切：

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

对于手动安装用户

如果你是手动安装 (方案 2 或 3)，你需要配置 Claude Desktop 或你的 MCP 客户端：

手动启动服务器

npm start

或者直接：

node build/index.js

手动配置 MCP 客户端

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

使用 NPX (推荐用于手动设置)

最简单的方法是使用 NPX，它会自动从 npm 安装并运行包，而不需要手动设置。该包可以在 https://www.npmjs.com/package/super-shell-mcp 上找到。

Roo Code 配置与 NPX

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

Claude Desktop 配置与 NPX

"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 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 执行模式及环境变量

默认禁用 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 Code: 为了安全原因，建议将 alwaysAllow 设置为空数组 []，这样会在执行任何命令之前提示批准。如果你想允许特定命令而不提示，可以将它们的名字添加到数组中，例如："alwaysAllow": ["execute_command", "get_whitelist"]。

对于 Claude Desktop: 为了安全原因，建议将 alwaysAllow 设置为 false。Claude Desktop 使用布尔值而不是数组，其中 false 表示所有命令都需要批准，true 表示所有命令都可以在不提示的情况下执行。

重要: alwaysAllow 参数由 MCP 客户端 (Roo Code 或 Claude Desktop) 处理，而不是由超级 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 方法（如配置部分所示）提供了几个优点：

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

从 GitHub 使用

如果你希望直接从 GitHub 使用最新开发版本：

"super-shell": {
  "command": "npx",
  "args": [
    "-y",
    "github:cfdude/super-shell-mcp"
  ],
  "alwaysAllow": [],  // 对于 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" 字段 - 将命令名称映射到入口点
- "files" 字段 - 指定发布时包含的文件
- "prepare" 脚本 - 确保安装时发生编译
TypeScript 配置:
- "module": "NodeNext" - 正确支持 ES 模块
- "moduleResolution": "NodeNext" - 与 ES 模块一致
自动安装和执行:
- MCP 客户端配置使用 npx -y 自动安装和运行包
- 进程在后台运行，不会占用终端窗口

发布流程:

# 更新 package.json 中的版本
npm version patch  # 或 minor/major 适当
# 构建并发布
npm publish

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

故障排除

跨平台问题

Windows 特定问题

PowerShell 脚本执行策略
- 问题: PowerShell 可能会因错误 "此系统上的脚本执行已被禁用" 而阻止脚本执行
- 解决方案: 以管理员身份运行 PowerShell 并执行 Set-ExecutionPolicy RemoteSigned 或