Super Shell MCP server

Super Shell MCP Server provides a secure way to execute shell commands across Windows, macOS, and Linux platforms through the Model Context Protocol (MCP). It features built-in command whitelisting and approval mechanisms to ensure security while allowing controlled shell access.

Installation

Using Smithery (Recommended for Claude Desktop)

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

Configuration

Option 1: Using NPX (Recommended)

Roo Code Configuration

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

Claude Desktop Configuration

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

Option 2: Using Local Installation

Roo Code Configuration

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

Claude Desktop Configuration

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

Specifying a Custom Shell

You can specify a custom shell by adding an extra parameter:

"super-shell": {
  "command": "node",
  "args": [
    "/path/to/super-shell-mcp/build/index.js",
    "--shell=/usr/bin/bash"
  ],
  "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"
  ],
  "alwaysAllow": [],
  "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 Information

{
  "tool": "get_platform_info",
  "parameters": {}
}

Execute Command

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

Get Whitelist

{
  "tool": "get_whitelist",
  "parameters": {}
}

Add to Whitelist

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

Update Security Level

{
  "tool": "update_security_level",
  "parameters": {
    "command": "python3",
    "securityLevel": "requires_approval"
  }
}

Remove from Whitelist

{
  "tool": "remove_from_whitelist",
  "parameters": {
    "command": "python3"
  }
}

Get Pending Commands

{
  "tool": "get_pending_commands",
  "parameters": {}
}

Approve Command

{
  "tool": "approve_command",
  "parameters": {
    "commandId": "command-uuid-here"
  }
}

Deny Command

{
  "tool": "deny_command",
  "parameters": {
    "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
• 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

Troubleshooting

Windows-Specific Issues

1. PowerShell Script Execution Policy

   • Issue: PowerShell may block script execution
   • Solution: Run PowerShell as Administrator and execute Set-ExecutionPolicy RemoteSigned

2. Path Separators

   • Issue: Windows uses backslashes in paths
   • Solution: Use double backslashes in JSON configuration files

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

Logging System

The server writes logs to logs/super-shell-mcp.log for debugging:

# View the entire log
cat logs/super-shell-mcp.log

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

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