Super Shell MCP server

The Super Shell MCP Server is a powerful tool that enables secure shell command execution across Windows, macOS, and Linux platforms. It includes robust security features like command whitelisting and approval workflows to protect your system when running commands through Claude Desktop or other MCP clients.

Installation Options

Claude Desktop Extension (Recommended)

The easiest way to install Super Shell MCP is as a Claude Desktop Extension:

1. Download the super-shell-mcp.dxt file from the latest release
2. Either:
   • Double-click the .dxt file while Claude Desktop is open
   • Or manually install via Claude Desktop Settings > Extensions > Add Extension
3. Start using immediately - no additional configuration needed!

Using Smithery

Install automatically via Smithery with:

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

Manual Installation

# 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

If you installed using the .dxt extension, you're ready to go! The extension handles everything automatically:

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

For Manual Installation Users

Starting the Server Manually

npm start

Or directly:

node build/index.js

Configuration for MCP Clients

Using NPX (Recommended)

For Roo Code:

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

For Claude Desktop:

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

Using Local Installation

For Roo Code:

"super-shell": {
  "command": "node",
  "args": [
    "/path/to/super-shell-mcp/build/index.js"
  ],
  "alwaysAllow": [],
  "disabled": false
}

For Claude Desktop:

"super-shell": {
  "command": "node",
  "args": [
    "/path/to/super-shell-mcp/build/index.js"
  ],
  "alwaysAllow": false,
  "disabled": false
}

You can optionally specify a custom shell:

"super-shell": {
  "command": "node",
  "args": [
    "/path/to/super-shell-mcp/build/index.js",
    "--shell=/usr/bin/bash"
  ],
  "alwaysAllow": false,
  "disabled": false
}

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

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

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

Available 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

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
• 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

Troubleshooting

Windows-Specific Issues

• PowerShell Script Execution Policy: Run PowerShell as Administrator and execute Set-ExecutionPolicy RemoteSigned
• Path Separators: Use double backslashes (\\) in JSON configuration files
• Command Not Found: Use Windows equivalents (dir instead of ls, findstr instead of grep)

macOS/Linux-Specific Issues

• Shell Permissions: Ensure the shell has appropriate permissions
• Environment Variables: Set environment variables in the shell's profile file

General Troubleshooting

• Shell Detection Issues: Explicitly specify the shell path in the configuration
• Command Execution Timeout: Increase the timeout value if needed
• Whitelist Management: Use the add_to_whitelist tool to add custom commands

Logging System

The server includes a comprehensive logging system that writes logs to logs/super-shell-mcp.log for easier debugging and monitoring.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "super-shell" '{"command":"npx","args":["-y","super-shell-mcp"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "super-shell": {
            "command": "npx",
            "args": [
                "-y",
                "super-shell-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "super-shell": {
            "command": "npx",
            "args": [
                "-y",
                "super-shell-mcp"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect