Super Shell MCP Server
Integrations
Provides Linux-specific shell integration with support for bash, sh, and zsh shells, along with platform-appropriate command whitelists.
Supports macOS-specific shell environments (zsh, bash, sh) with tailored command whitelists and security considerations for the platform.
Enables execution of shell commands across multiple platforms (Windows, macOS, Linux) with platform-specific command whitelists and security levels.
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.
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
- 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
Installing via Smithery
To install Super Shell MCP Server for Claude Desktop automatically via Smithery:
Installing Manually
Usage
Starting the Server
Or directly:
Configuring in Roo Code and Claude Desktop
Both Roo Code and Claude Desktop use a similar configuration format for MCP servers. Here's how to set up the Super Shell MCP server:
Option 1: Using NPX (Recommended)
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
Claude Desktop Configuration with NPX
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
):
You can optionally specify a custom shell by adding a shell parameter:
Windows 11 example
Claude Desktop Configuration
Add the following to your Claude Desktop configuration file (located at ~/Library/Application Support/Claude/claude_desktop_config.json
):
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
- Roo Code:
- 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
- cmd.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
- Roo Code:
- Shell path examples:
- zsh:
/bin/zsh
- bash:
/bin/bash
- sh:
/bin/sh
- zsh:
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
- Roo Code:
- Shell path examples:
- bash:
/bin/bash
- sh:
/bin/sh
- zsh:
/usr/bin/zsh
- bash:
You can optionally specify a custom shell:
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
tofalse
is recommended for security reasons. Claude Desktop uses a boolean value instead of an array, wherefalse
means all commands require approval andtrue
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.
get_whitelist
Get the list of whitelisted commands.
add_to_whitelist
Add a command to the whitelist.
update_security_level
Update the security level of a whitelisted command.
remove_from_whitelist
Remove a command from the whitelist.
get_pending_commands
Get the list of commands pending approval.
approve_command
Approve a pending command.
deny_command
Deny a pending command.
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 contentspwd
- Print working directoryecho
- Print text to standard outputcat
- Concatenate and print filesgrep
- Search for patterns in filesfind
- Find files in a directory hierarchycd
- Change directoryhead
- Output the first part of filestail
- Output the last part of fileswc
- Print newline, word, and byte counts
Windows-specific Safe Commands
dir
- List directory contentstype
- Display the contents of a text filefindstr
- Search for strings in fileswhere
- Locate programswhoami
- Display current userhostname
- Display computer namever
- Display operating system version
Commands Requiring Approval
Windows Commands Requiring Approval
copy
- Copy filesmove
- Move filesmkdir
- Create directoriesrmdir
- Remove directoriesrename
- Rename filesattrib
- Change file attributes
Unix Commands Requiring Approval
mv
- Move (rename) filescp
- Copy files and directoriesmkdir
- Create directoriestouch
- Change file timestamps or create empty fileschmod
- Change file mode bitschown
- Change file owner and group
Forbidden Commands
Windows Forbidden Commands
del
- Delete fileserase
- Delete filesformat
- Format a diskrunas
- Execute a program as another user
Unix Forbidden Commands
rm
- Remove files or directoriessudo
- 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 ofexec
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:
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:
- No Manual Setup: No need to clone the repository, install dependencies, or build the project
- Automatic Updates: Always uses the latest published version
- Cross-Platform Compatibility: Works the same way on Windows, macOS, and Linux
- Simplified Configuration: Shorter configuration with no absolute paths
- Reduced Maintenance: No local files to manage or update
Using from GitHub
If you prefer to use the latest development version directly from GitHub:
Publishing Your Own Version
If you want to publish your own modified version to npm:
- Update the package.json with your details
- Ensure the "bin" field is properly configured:Copy
- Publish to npm:Copy
NPX Best Practices
For optimal integration with MCP clients using NPX, this project follows these best practices:
- Executable Entry Point: The main file includes a shebang line (
#!/usr/bin/env node
) and is made executable during build. - 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
- TypeScript Configuration:
"module": "NodeNext"
- Proper ES Modules support"moduleResolution": "NodeNext"
- Consistent with ES Modules
- 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
- The MCP client configuration uses
- Publishing Process:Copy
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
- 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
- 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
- Issue: Windows uses backslashes (
- Command Not Found
- Issue: Windows doesn't have Unix commands like
ls
,grep
, etc. - Solution: Use Windows equivalents (
dir
instead ofls
,findstr
instead ofgrep
)
- Issue: Windows doesn't have Unix commands like
macOS/Linux-Specific Issues
- Shell Permissions
- Issue: Permission denied when executing commands
- Solution: Ensure the shell has appropriate permissions with
chmod +x /path/to/shell
- 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
- Shell Detection Issues
- Issue: Server fails to detect the correct shell
- Solution: Explicitly specify the shell path in the configuration
- 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:
- 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
- Default:
- Log Levels
- INFO: General operational information
- DEBUG: Detailed debugging information
- ERROR: Error conditions and exceptions
- Viewing Logs
- Use standard file viewing commands to check logs:Copy
- Use standard file viewing commands to check logs:
- Log Content
- Server startup and configuration
- Command execution requests and results
- Approval workflow events (pending, approved, denied)
- Error conditions and troubleshooting information
- Whitelist Management
- Issue: Need to add custom commands to whitelist
- Solution: Use the
add_to_whitelist
tool to add commands specific to your environment
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.
This server cannot be installed
An MCP server that enables secure execution of shell commands across Windows, macOS, and Linux with built-in whitelisting and approval mechanisms for enhanced security.