Awesome Linux MCP Server

# 🚀 Quick Guide: ParrotOS VM in UTM + Cursor IDE + AWESOME Linux MCP This guide provides a complete setup for running a **ParrotOS VM in UTM** on macOS, with **AWESOME Linux MCP** for remote control, accessible from **Cursor IDE** on the host macOS system. ## 🎯 Primary Use Case ```mermaid graph TB subgraph "macOS Host" A[Cursor IDE] --> B[AWESOME Linux MCP] B --> C[SSH Connection] A --> D[Browser Automation] end subgraph "UTM Virtual Machine" C --> E[ParrotOS Guest] E --> F[Linux Commands] E --> G[System Monitoring] E --> H[Browser Automation] end D --> H style A fill:#e1f5fe style B fill:#fff3e0 style E fill:#e8f5e8 ``` **Architecture Overview:** - **Host**: macOS with Cursor IDE and AWESOME Linux MCP server - **Guest**: ParrotOS VM in UTM with SSH server - **Connection**: SSH tunnel from host MCP server to guest ParrotOS - **Control**: Cursor IDE uses MCP to control ParrotOS remotely ## 📋 Prerequisites ### Host System (macOS) - macOS 12.0 or later - UTM app installed ([utm.app](https://mac.getutm.app/)) - Cursor IDE ([cursor.com](https://cursor.com/)) - Python 3.8+ with pip - Chrome/Chromium browser ### Guest System (ParrotOS) - ParrotOS ISO ([parrotsec.org/download](https://www.parrotsec.org/download/)) - SSH server configured - Network connectivity to host ## 🛠️ Step 1: Set Up ParrotOS VM in UTM ### 1.1 Download ParrotOS ```bash # Download ParrotOS Security Edition (recommended for this use case) curl -L -o parrot-security.iso "https://deb.parrot.sh/parrot/iso/current/Parrot-security-6.0_amd64.iso" ``` ### 1.2 Create UTM Virtual Machine 1. **Open UTM** and click **+** to create a new VM 2. **Select "Virtualize"** → **"Linux"** 3. **Choose the ParrotOS ISO** you downloaded 4. **Configure VM Settings:** - **Name**: `ParrotOS-MCP` - **Memory**: `4096 MB` (4GB recommended) - **CPU Cores**: `2` cores - **Storage**: `40 GB` (expandable) - **Network**: `Shared Network` (NAT) ### 1.3 Install ParrotOS 1. **Start the VM** and boot from ISO 2. **Follow installation wizard:** - **Language**: English - **Location**: Your location - **Keyboard**: Default - **Hostname**: `parrot-mcp` - **Username**: `mcpuser` (or your preferred username) - **Password**: Set a strong password - **Partition**: Guided - use entire disk 3. **Complete installation** and reboot ### 1.4 Configure ParrotOS for Remote Access #### 1.4.1 Update System ```bash # Update package lists and upgrade system sudo apt update && sudo apt upgrade -y # Install essential tools sudo apt install -y openssh-server curl wget htop neofetch ``` #### 1.4.2 Configure SSH Server ```bash # Enable SSH service sudo systemctl enable ssh sudo systemctl start ssh # Configure SSH for better security (optional but recommended) sudo nano /etc/ssh/sshd_config # Add these lines (uncomment/modify): # Port 22 # PermitRootLogin no # PasswordAuthentication yes # PubkeyAuthentication yes # Restart SSH service sudo systemctl restart ssh ``` #### 1.4.3 Configure Network (Static IP for UTM) ```bash # Check current network configuration ip addr show # Configure netplan for static IP (if using netplan) sudo nano /etc/netplan/01-netcfg.yaml # Example configuration: network: version: 2 renderer: networkd ethernets: enp0s1: dhcp4: no addresses: [192.168.65.100/24] # Use UTM shared network IP gateway4: 192.168.65.1 nameservers: addresses: [8.8.8.8, 1.1.1.1] # Apply network configuration sudo netplan apply ``` #### 1.4.4 Install Browser Automation Dependencies ```bash # Install Chrome for browser automation wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add - echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /etc/apt/sources.list.d/google-chrome.list sudo apt update sudo apt install -y google-chrome-stable # Install Python and pip (if not already installed) sudo apt install -y python3 python3-pip python3-venv # Install system monitoring tools sudo apt install -y htop iotop sysstat ``` #### 1.4.5 Create MCP User (Optional) ```bash # Create dedicated user for MCP operations sudo useradd -m -s /bin/bash mcpuser sudo usermod -aG sudo mcpuser # Add to sudo group if needed sudo passwd mcpuser # Configure passwordless sudo for automation (CAUTION: Use carefully) echo "mcpuser ALL=(ALL) NOPASSWD: ALL" | sudo tee /etc/sudoers.d/mcpuser ``` ### 1.5 Test SSH Connectivity From **macOS host terminal**: ```bash # Test SSH connection to VM ssh mcpuser@192.168.65.100 # Use your VM's IP # Test commands hostname whoami df -h free -h ``` ## 🐍 Step 2: Set Up AWESOME Linux MCP on macOS Host ### 2.1 Clone and Setup ```bash # Navigate to your workspace cd /path/to/your/workspace # Clone or ensure AWESOME_LINUX_MCP is available # (Assuming it's already created in the previous steps) # Navigate to the project cd AWESOME_LINUX_MCP # Activate virtual environment source venv/bin/activate # Install/update dependencies pip install -r requirements.txt ``` ### 2.2 Configure Environment ```bash # Copy environment template cp config.example.env .env # Edit configuration nano .env ``` **Contents of .env:** ```bash # SSH Configuration for ParrotOS VM SSH_HOST=192.168.65.100 SSH_PORT=22 SSH_USER=mcpuser SSH_KEY_PATH= SSH_PASSWORD=your-vm-password # Browser Configuration BROWSER_HEADLESS=true # Logging LOG_LEVEL=INFO ``` ### 2.3 Test MCP Server ```bash # Test the server (should start without errors) python linux_mcp_server.py & # Press Ctrl+C after a few seconds to stop # Run tests python test_server.py ``` ## 🖥️ Step 3: Configure Cursor IDE on macOS Host ### 3.1 Install MCP Extension (if needed) Cursor should have built-in MCP support. If not: 1. Open Cursor 2. Go to Extensions (`Cmd+Shift+X`) 3. Search for "MCP" or "Model Context Protocol" 4. Install the official MCP extension ### 3.2 Configure Claude Desktop MCP Settings **File:** `~/Library/Application Support/Claude/claude_desktop_config.json` ```json { "mcpServers": { "linux-mcp": { "command": "python3", "args": ["/Users/YOUR_USERNAME/PATH/TO/AWESOME_LINUX_MCP/linux_mcp_server.py"], "env": { "SSH_HOST": "192.168.65.100", "SSH_USER": "mcpuser", "SSH_PASSWORD": "your-vm-password", "BROWSER_HEADLESS": "true", "LOG_LEVEL": "INFO" } } } } ``` **Important:** Replace `/Users/YOUR_USERNAME/PATH/TO/AWESOME_LINUX_MCP/` with the actual absolute path. ### 3.3 Verify Configuration ```bash # Test MCP server startup cd /path/to/AWESOME_LINUX_MCP source venv/bin/activate python linux_mcp_server.py # In another terminal, test MCP protocol echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python linux_mcp_server.py ``` ## 🔧 Step 4: System Configuration Details ### Host System (macOS) Configuration #### 4.1.1 Network Configuration ```bash # Check UTM network interface ifconfig | grep -A 5 -B 5 "utun" # Verify VM connectivity ping 192.168.65.100 # Check SSH config cat ~/.ssh/config ``` #### 4.1.2 Firewall Settings ```bash # Allow SSH connections (if firewall is blocking) sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /usr/bin/ssh sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblock /usr/bin/ssh ``` #### 4.1.3 Python Environment ```bash # Ensure Python 3.8+ is available python3 --version # Install virtualenv if needed pip3 install virtualenv ``` ### Guest System (ParrotOS) Configuration #### 4.2.1 SSH Server Configuration ```bash # Verify SSH service status sudo systemctl status ssh # Check SSH configuration sudo cat /etc/ssh/sshd_config | grep -E "(Port|PermitRoot|PasswordAuth|PubkeyAuth)" # Test local SSH ssh localhost ``` #### 4.2.2 Network Configuration ```bash # Check network interfaces ip addr show # Check routing ip route show # Test internet connectivity ping -c 3 8.8.8.8 # Check DNS resolution nslookup google.com ``` #### 4.2.3 Browser Setup ```bash # Verify Chrome installation google-chrome --version # Test headless mode google-chrome --headless --disable-gpu --screenshot https://example.com # Check display server (should work in headless mode) echo $DISPLAY ``` #### 4.2.4 System Resources ```bash # Check available resources free -h df -h nproc cat /proc/meminfo | head -10 ``` ## 🧪 Step 5: Testing the Complete Setup ### 5.1 Test SSH Connection from MCP Server ```bash # On macOS host, in AWESOME_LINUX_MCP directory source venv/bin/activate python -c " import os os.environ['SSH_HOST'] = '192.168.65.100' os.environ['SSH_USER'] = 'mcpuser' os.environ['SSH_PASSWORD'] = 'your-password' from linux_mcp_server import execute_command import asyncio async def test(): result = await execute_command('uname -a') print('SSH Test Result:', result[:100]) asyncio.run(test()) " ``` ### 5.2 Test Browser Automation ```bash # Test browser functionality python -c " import asyncio from linux_mcp_server import puppeteer_navigate, puppeteer_screenshot async def test(): result1 = await puppeteer_navigate('https://example.com') print('Browser Test:', result1[:100]) asyncio.run(test()) " ``` ### 5.3 Test in Cursor IDE 1. **Open Cursor** and start a new chat 2. **Ask Cursor to use the MCP tools:** ``` "Check the system information on my ParrotOS VM" "List the contents of the /home directory on the VM" "Take a screenshot of https://example.com" "Execute 'ls -la /etc' on the ParrotOS system" ``` 3. **Verify** that Cursor can: - Connect to your ParrotOS VM via SSH - Execute commands and return results - Perform browser automation - Access system monitoring data ## 🔍 Troubleshooting ### Common Issues #### SSH Connection Problems ```bash # Check VM IP address # In UTM: VM Settings → Network → IP Address # Test from host ssh mcpuser@VM_IP # Check SSH service in VM sudo systemctl status ssh sudo netstat -tlnp | grep :22 ``` #### Browser Automation Issues ```bash # Test Chrome in VM google-chrome --version # Test headless mode google-chrome --headless --disable-gpu --dump-dom https://example.com ``` #### MCP Server Issues ```bash # Check Python environment source venv/bin/activate python --version # Test imports python -c "import paramiko, pyppeteer, psutil; print('Imports OK')" # Check environment variables python -c "import os; print('SSH_HOST:', os.getenv('SSH_HOST'))" ``` #### Cursor IDE Issues ```bash # Check Claude Desktop config path ls -la ~/Library/Application\ Support/Claude/ # Validate JSON syntax python -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json # Restart Claude Desktop after config changes ``` ### Performance Optimization #### UTM VM Settings - **CPU**: Allocate 2-4 cores - **Memory**: 4-8 GB RAM - **Storage**: 40+ GB disk space - **Network**: Shared Network (NAT) for best compatibility #### MCP Server Tuning ```bash # Adjust timeouts in .env COMMAND_TIMEOUT=30 SSH_TIMEOUT=10 # Enable debug logging LOG_LEVEL=DEBUG ``` ## 📚 Advanced Configuration ### SSH Key Authentication (More Secure) ```bash # On macOS host ssh-keygen -t ed25519 -C "mcp-parrot-vm" # Copy public key to VM ssh-copy-id mcpuser@192.168.65.100 # Update .env to use key instead of password SSH_KEY_PATH=/Users/YOUR_USERNAME/.ssh/id_ed25519 SSH_PASSWORD= ``` ### Multiple VMs ```bash # Create separate .env files for different VMs cp .env .env.vm1 cp .env .env.vm2 # Run different servers for each VM SSH_HOST=192.168.65.100 python linux_mcp_server.py # VM1 SSH_HOST=192.168.65.101 python linux_mcp_server.py # VM2 ``` ### System Monitoring Integration ```bash # Install monitoring tools in ParrotOS sudo apt install -y prometheus-node-exporter # Configure for remote access sudo nano /etc/default/prometheus-node-exporter # Add: ARGS="--web.listen-address=0.0.0.0:9100" sudo systemctl restart prometheus-node-exporter ``` ## 🎯 Success Indicators - ✅ **SSH Connection**: Can connect from macOS to ParrotOS VM - ✅ **Command Execution**: MCP tools return results from VM - ✅ **Browser Automation**: Can navigate and screenshot websites - ✅ **Cursor Integration**: IDE shows MCP tools and can use them - ✅ **System Monitoring**: Can retrieve CPU, memory, disk stats - ✅ **File Operations**: Can list directories and execute scripts ## 📞 Support ### Getting Help 1. **Check logs**: Look at Cursor and MCP server output 2. **Test components**: Verify SSH, browser, and Python individually 3. **Network issues**: Ensure UTM networking is properly configured 4. **Configuration**: Double-check all configuration files ### Useful Commands ```bash # Check VM status in UTM # Check network settings in VM: ip addr show # Test SSH: ssh -v mcpuser@VM_IP # Check MCP: python linux_mcp_server.py (should start without errors) # Test tools: python test_server.py ``` --- **🎉 Congratulations!** You now have a fully functional AI-controlled ParrotOS environment accessible from Cursor IDE on your macOS system. The AWESOME Linux MCP server provides comprehensive remote control capabilities for both system administration and web automation tasks.