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.

{
  "commandId": "command-uuid-here"
}

deny_command

Deny a pending command.

{
  "commandId": "command-uuid-here",
  "reason": "This command is potentially dangerous"
}

Default Whitelisted Commands

The server includes platform-specific command whitelists that are automatically selected based on the detected platform.

Common Safe Commands (All Platforms)

• echo - Print text to standard output

Unix-like Safe Commands (macOS/Linux)

• ls - List directory contents
• pwd - Print working directory
• echo - Print text to standard output
• cat - Concatenate and print files
• grep - Search for patterns in files
• find - Find files in a directory hierarchy
• cd - Change directory
• head - Output the first part of files
• tail - Output the last part of files
• wc - Print newline, word, and byte counts

Windows-specific Safe Commands

• dir - List directory contents
• type - Display the contents of a text file
• findstr - Search for strings in files
• where - Locate programs
• whoami - Display current user
• hostname - Display computer name
• ver - Display operating system version

Commands Requiring Approval

Windows Commands Requiring Approval

• copy - Copy files
• move - Move files
• mkdir - Create directories
• rmdir - Remove directories
• rename - Rename files
• attrib - Change file attributes

Unix Commands Requiring Approval

• mv - Move (rename) files
• cp - Copy files and directories
• mkdir - Create directories
• touch - Change file timestamps or create empty files
• chmod - Change file mode bits
• chown - Change file owner and group

Forbidden Commands

Windows Forbidden Commands

• del - Delete files
• erase - Delete files
• format - Format a disk
• runas - Execute a program as another user

Unix Forbidden Commands

• rm - Remove files or directories
• sudo - Execute a command as another user

Security Considerations

• All commands are executed with the permissions of the user running the MCP server
• Commands requiring approval are held in a queue until explicitly approved
• Forbidden commands are never executed
• The server uses Node.js's execFile instead of exec to prevent shell injection
• Arguments are validated against allowed patterns when specified

Extending the Whitelist

You can extend the whitelist by using the add_to_whitelist tool. For example:

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

NPM Package Information

Super Shell MCP is available as an npm package at https://www.npmjs.com/package/super-shell-mcp.

Benefits of Using NPX

Using the NPX method (as shown in Option 1 of the Configuration section) offers several advantages:

1. No Manual Setup: No need to clone the repository, install dependencies, or build the project
2. Automatic Updates: Always uses the latest published version
3. Cross-Platform Compatibility: Works the same way on Windows, macOS, and Linux
4. Simplified Configuration: Shorter configuration with no absolute paths
5. Reduced Maintenance: No local files to manage or update

Using from GitHub

If you prefer to use the latest development version directly from GitHub:

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

Publishing Your Own Version

If you want to publish your own modified version to npm:

1. Update the package.json with your details
2. Ensure the "bin" field is properly configured:

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

3. Publish to npm:

   npm publish

NPX Best Practices

For optimal integration with MCP clients using NPX, this project follows these best practices:

1. Executable Entry Point: The main file includes a shebang line (#!/usr/bin/env node) and is made executable during build.

2. Package Configuration:

   • "type": "module" - Ensures ES Modules are used
   • "bin" field - Maps the command name to the entry point
   • "files" field - Specifies which files to include when publishing
   • "prepare" script - Ensures compilation happens on install

3. TypeScript Configuration:

   • "module": "NodeNext" - Proper ES Modules support
   • "moduleResolution": "NodeNext" - Consistent with ES Modules

4. Automatic Installation and Execution:

   • The MCP client configuration uses npx -y to automatically install and run the package
   • No terminal window is tied up as the process runs in the background

5. Publishing Process:

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

These practices ensure the MCP server can be started automatically by the MCP client without requiring a separate terminal window, improving user experience and operational efficiency.

Troubleshooting

Cross-Platform Issues

Windows-Specific Issues

1. PowerShell Script Execution Policy

   • Issue: PowerShell may block script execution with the error "Execution of scripts is disabled on this system"
   • Solution: Run PowerShell as Administrator and execute Set-ExecutionPolicy RemoteSigned or use the -ExecutionPolicy Bypass parameter when configuring the shell

2. Path Separators

   • Issue: Windows uses backslashes (\) in paths, which need to be escaped in JSON
   • Solution: Use double backslashes (\\) in JSON configuration files, e.g., C:\\Windows\\System32\\cmd.exe

3. Command Not Found

   • Issue: Windows doesn't have Unix commands like ls, grep, etc.
   • Solution: Use Windows equivalents (dir instead of ls, findstr instead of grep)

macOS/Linux-Specific Issues

1. Shell Permissions

   • Issue: Permission denied when executing commands
   • Solution: Ensure the shell has appropriate permissions with chmod +x /path/to/shell

2. Environment Variables

   • Issue: Environment variables not available in MCP server
   • Solution: Set environment variables in the shell's profile file (.zshrc, .bashrc, etc.)

General Troubleshooting

1. Shell Detection Issues

   • Issue: Server fails to detect the correct shell
   • Solution: Explicitly specify the shell path in the configuration

2. Command Execution Timeout

   • Issue: Commands taking too long and timing out
   • Solution: Increase the timeout value in the command service constructor

Logging System

The server includes a comprehensive logging system that writes logs to a file for easier debugging and monitoring:

1. Log File Location

   • Default: logs/super-shell-mcp.log in the server's directory
   • The logs directory is created automatically and tracked by Git (with a .gitkeep file)
   • Log files themselves are excluded from Git via .gitignore
   • Contains detailed information about server operations, command execution, and approval workflow

2. Log Levels

   • INFO: General operational information
   • DEBUG: Detailed debugging information
   • ERROR: Error conditions and exceptions

3. Viewing Logs

   • Use standard file viewing commands to check logs:

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

4. Log Content

   • Server startup and configuration
   • Command execution requests and results
   • Approval workflow events (pending, approved, denied)
   • Error conditions and troubleshooting information

5. Whitelist Management

   • Issue: Need to add custom commands to whitelist
   • Solution: Use the add_to_whitelist tool to add commands specific to your environment

Known Issues

Android Studio Otter 2 Feature Drop Compatibility

Affected Version: Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 (Build #AI-252.25557.131.2522.14357309)

Issue: Android Studio's MCP client implementation incorrectly serializes array parameters as strings when calling the execute_command tool. This causes commands with arguments to fail with the error:

Error: Expected array, received string

Example:

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

Root Cause: This is a bug in Android Studio's MCP client, not in super-shell-mcp. The server correctly defines args as type array in its schema, and the issue has been verified to work correctly with:

• Claude Desktop
• Official MCP SDK clients
• Other MCP-compatible tools

Status: This is an Android Studio bug. The super-shell-mcp server implements the MCP specification correctly.

Workaround: None currently available. Users experiencing this issue should report it to the Android Studio/JetBrains team.

References:

• Issue reported: #20
• Related documentation: Android Studio Gemini MCP Integration

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.