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:

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:

3. TypeScript Configuration:

4. Automatic Installation and Execution:

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

2. Path Separators

3. Command Not Found

macOS/Linux-Specific Issues

1. Shell Permissions

2. Environment Variables

General Troubleshooting

1. Shell Detection Issues

2. Command Execution Timeout

Logging System

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

1. Log File Location

2. Log Levels

3. Viewing 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

3. Whitelist Management

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.