Super Shell MCP Server

Super Shell MCP 服务

一个 MCP（Model Context Protocol）服务，可在多个平台（Windows、macOS、Linux）上执行 shell 命令。此服务通过内置的白名单和审批机制，提供安全的 shell 命令执行方式。

🎉 现已作为 Claude Desktop 扩展提供！ 使用 .dxt 软件包一键安装，无需开发工具或配置。

功能

• 通过 MCP 在 Windows、macOS 和 Linux 上执行 shell 命令
• 自动检测平台并选择 shell
• 支持多种 shell：
  • Windows：cmd.exe、PowerShell
  • macOS：zsh、bash、sh
  • Linux：bash、sh、zsh
• 默认禁用 shell 解析，以消除命令注入风险；也提供显式启用模式，适用于可信工作流
• 命令白名单及安全级别：
  • 安全：无需审批即可执行的命令
  • 需要审批：执行前需要明确审批的命令
  • 禁止：明确禁止执行的命令
• 平台专属命令白名单
• 针对潜在危险命令的非阻塞式审批工作流
• 完善的日志系统，支持基于文件的日志
• 完善的命令管理工具
• 用于诊断的平台信息工具

安装

选项 1：Claude Desktop 扩展（.dxt）——推荐

一键安装到 Claude Desktop：

1. 从最新版本下载 super-shell-mcp.dxt 文件

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

   或

   手动安装：

   • 打开 Claude Desktop
   • 前往 Settings > Extensions
   • 点击 "Add Extension"
   • 选择下载的 super-shell-mcp.dxt 文件

3. 配置（可选）：根据需要设置自定义 shell 路径

4. 开始使用——扩展已可立即使用！

✅ 使用 DXT 安装的优势：

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

选项 2：通过 Smithery 安装

要通过 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 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（手动设置推荐）

使用 Super Shell MCP 最简单的方式是通过 NPX，它会自动从 npm 安装并运行软件包，无需手动设置。该软件包可从 NPM 获取：https://www.npmjs.com/package/super-shell-mcp。

使用 NPX 配置 Roo Code

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

使用 NPX 配置 Claude Desktop

"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：可选，覆盖默认的 30s 命令超时时间（毫秒）。

⚠️ 启用 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）处理，而不是由 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，以防止 Shell 注入
• 指定允许的模式时，会根据这些模式验证参数

扩展白名单

你可以使用 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 所示）有以下优势：

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"
   }
   

3. 发布到 npm：

   npm publish
   

NPX 最佳实践

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

1. 可执行入口点：主文件包含 shebang 行（#!/usr/bin/env node），并会在构建期间设置为可执行。

2. 包配置：

   • "type": "module" - 确保使用 ES Modules
   • "bin" 字段 - 将命令名称映射到入口点
   • "files" 字段 - 指定发布时要包含的文件
   • "prepare" 脚本 - 确保安装时执行编译

3. TypeScript 配置：

   • "module": "NodeNext" - 提供正确的 ES Modules 支持
   • "moduleResolution": "NodeNext" - 与 ES Modules 保持一致

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 可能会阻止脚本执行，并报错 "Execution of scripts is disabled on this system"
   • 解决方案：以管理员身份运行 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. 查看日志

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

     # 查看完整日志
     cat logs/super-shell-mcp.log
     
     # 实时跟踪日志更新
     tail -f logs/super-shell-mcp.log
     

4. 日志内容

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

5. 白名单管理

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

已知问题

Android Studio Otter 2 Feature Drop 兼容性

受影响版本：Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3（Build #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 客户端中的错误，并非 super-shell-mcp 的问题。服务在架构中正确地将 args 定义为 array 类型，并已验证以下客户端可正常运行：

• Claude Desktop
• 官方 MCP SDK 客户端
• 其他兼容 MCP 的工具

状态：这是 Android Studio 的错误。super-shell-mcp 服务正确实现了 MCP 规范。

解决方法：目前暂无。遇到此问题的用户应向 Android Studio/JetBrains 团队报告。

参考资料：

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

许可证

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