Super Shell

Super Shell MCP Server

An MCP (Model Context Protocol) server for executing shell commands across multiple platforms (Windows, macOS, Linux). This server provides a secure way to execute shell commands with built-in whitelisting and approval mechanisms.

🎉 Now available as a Claude Desktop Extension! Install with one click using the .dxt package - no developer tools or configuration required.

Features

• Execute shell commands through MCP on Windows, macOS, and Linux
• Automatic platform detection and shell selection
• Support for multiple shells:
  • Windows: cmd.exe, PowerShell
  • macOS: zsh, bash, sh
  • Linux: bash, sh, zsh
• Shell parsing disabled by default to eliminate command-injection risk, with an explicit opt-in mode for trusted workflows
• Command whitelisting with security levels:
  • Safe: Commands that can be executed without approval
  • Requires Approval: Commands that need explicit approval before execution
  • Forbidden: Commands that are explicitly blocked
• Platform-specific command whitelists
• Non-blocking approval workflow for potentially dangerous commands
• Comprehensive logging system with file-based logs
• Comprehensive command management tools
• Platform information tool for diagnostics

Installation

Option 1: Claude Desktop Extension (.dxt) - Recommended

One-Click Installation for Claude Desktop:

1. Download the super-shell-mcp.dxt file from the latest release

2. Quick Install: Double-click the .dxt file while Claude Desktop is open

   OR

   Manual Install:

   • Open Claude Desktop
   • Go to Settings > Extensions
   • Click "Add Extension"
   • Select the downloaded super-shell-mcp.dxt file

3. Configure (optional): Set custom shell path if needed

4. Start using - The extension is ready to use immediately!

✅ Benefits of DXT Installation:

• No developer tools required (Node.js, Python, etc.)
• No manual configuration files
• Automatic dependency management
• One-click installation and updates
• Secure credential storage in OS keychain

Option 2: Installing via Smithery

To install Super Shell MCP Server for Claude Desktop automatically via Smithery:

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

Option 3: Installing Manually

# 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

Usage

For Claude Desktop Extension Users (.dxt)

If you installed using the .dxt extension (Option 1), you're ready to go! No additional configuration needed. The extension handles everything automatically:

• ✅ Automatic startup when Claude Desktop launches
• ✅ Platform detection and appropriate shell selection
• ✅ Built-in security with command whitelisting and approval workflows
• ✅ Optional configuration via Claude Desktop's extension settings

For Manual Installation Users

If you installed manually (Option 2 or 3), you'll need to configure Claude Desktop or your MCP client:

Starting the Server Manually

npm start

Or directly:

node build/index.js

Manual Configuration for MCP Clients

For manual installations, both Roo Code and Claude Desktop use a similar configuration format for MCP servers:

Using NPX (Recommended for Manual Setup)

The easiest way to use Super Shell MCP is with NPX, which automatically installs and runs the package from npm without requiring manual setup. The package is available on NPM at https://www.npmjs.com/package/super-shell-mcp.

Roo Code Configuration with NPX

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

Claude Desktop Configuration with NPX

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

Option 2: Using Local Installation

If you prefer to use a local installation, add the following to your Roo Code MCP settings configuration file (located at ~/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
}

You can optionally provide a trusted shell and opt into shell parsing by setting environment variables instead of command-line flags:

"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 example:

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

Add the following to your Claude Desktop configuration file (located at ~/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
}

For Windows users, the configuration file is typically located at %APPDATA%\Claude\claude_desktop_config.json.

Platform-Specific Configuration

Windows

• Default shell: cmd.exe (or PowerShell if available)
• Configuration paths:
  • Roo Code: %APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json
  • Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json
• Shell path examples:
  • 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

• Default shell: /bin/zsh
• Configuration paths:
  • 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 path examples:
  • zsh: /bin/zsh
  • bash: /bin/bash
  • sh: /bin/sh

Linux

• Default shell: /bin/bash (or $SHELL environment variable)
• Configuration paths:
  • Roo Code: ~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json
  • Claude Desktop: ~/.config/Claude/claude_desktop_config.json
• Shell path examples:
  • bash: /bin/bash
  • sh: /bin/sh
  • zsh: /usr/bin/zsh

Shell Execution Modes & Environment Variables

Shell parsing is disabled by default for security. Customise behaviour with the following environment variables:

• SUPER_SHELL_USE_SHELL: set to true (or 1/yes/on) to enable shell parsing for trusted workflows. Omit or set to false to keep the safer default.
• CUSTOM_SHELL: optional path to the shell executable used when shell parsing is enabled.
• SUPER_SHELL_COMMAND_TIMEOUT: optional override (milliseconds) for the default 30s command timeout.

⚠️ Enabling shell parsing reintroduces the risk of command injection. Only enable it when you fully trust the command source and payload.

Replace /path/to/super-shell-mcp with the actual path where you cloned the repository.

Note:

• For Roo Code: Setting alwaysAllow to an empty array [] is recommended for security reasons, as it will prompt for approval before executing any commands. If you want to allow specific commands without prompting, you can add their names to the array, for example: "alwaysAllow": ["execute_command", "get_whitelist"].
• For Claude Desktop: Setting alwaysAllow to false is recommended for security reasons. Claude Desktop uses a boolean value instead of an array, where false means all commands require approval and true means all commands are allowed without prompting.

Important: The alwaysAllow parameter is processed by the MCP client (Roo Code or Claude Desktop), not by the Super Shell MCP server itself. The server will work correctly with either format, as the client handles the approval process before sending requests to the server.

Available Tools

The server exposes the following MCP tools:

get_platform_info

Get information about the current platform and shell.

{}

execute_command

Execute a shell command on the current platform.

{
  "command": "ls",
  "args": ["-la"]
}

get_whitelist

Get the list of whitelisted commands.

{}

add_to_whitelist

Add a command to the whitelist.

{
  "command": "python3",
  "securityLevel": "safe",
  "description": "Run Python 3 scripts"
}

update_security_level

Update the security level of a whitelisted command.

{
  "command": "python3",
  "securityLevel": "requires_approval"
}

remove_from_whitelist

Remove a command from the whitelist.

{
  "command": "python3"
}

get_pending_commands

Get the list of commands pending approval.

{}

approve_command

Approve a pending command.

---

README truncated. View full README on GitHub.