Awesome Linux MCP Server

# Awesome Linux MCP Server A comprehensive Model Context Protocol (MCP) server that provides AI models with secure control over remote Linux servers and browser automation capabilities. ## 🚀 Features ### SSH-Based Linux Server Control - **Remote Command Execution**: Run commands securely on remote Linux servers via SSH - **Script Management**: Execute and create bash scripts on remote systems - **File System Operations**: List directories with detailed information - **System Monitoring**: Comprehensive CPU, memory, and disk usage monitoring ### Browser Automation - **Web Navigation**: Navigate to URLs with automatic wait conditions - **Interactive Controls**: Click, hover, fill forms, and select dropdown options - **Screenshot Capture**: Full page or element-specific screenshots - **JavaScript Execution**: Run custom JavaScript in browser context - **Real-time Monitoring**: Console logs and network request tracking ### MCP Resources - **Console Logs**: Access browser console output as MCP resources - **Screenshots**: Current browser screenshots as base64 data - **Network Details**: HTTP request/response monitoring data ## 🛠️ Installation ### Prerequisites - Python 3.8+ - SSH access to a Linux server - Chrome/Chromium browser (for browser automation) ### Setup 1. **Clone or create the project directory:** ```bash mkdir awesome-linux-mcp cd awesome-linux-mcp ``` 2. **Install dependencies:** ```bash pip install -r requirements.txt ``` 3. **Configure environment variables:** ```bash cp config.example.env .env # Edit .env with your SSH and configuration settings ``` 4. **Set up SSH access:** - Ensure you have SSH access to your target Linux server - Use either SSH key authentication (recommended) or password authentication - Test SSH connection manually first: `ssh user@host` ## ⚙️ Configuration ### Environment Variables | Variable | Description | Default | Required | |----------|-------------|---------|----------| | `SSH_HOST` | Remote Linux server hostname/IP | localhost | Yes | | `SSH_PORT` | SSH port | 22 | No | | `SSH_USER` | SSH username | - | Yes | | `SSH_KEY_PATH` | Path to SSH private key | - | No* | | `SSH_PASSWORD` | SSH password | - | No* | | `BROWSER_HEADLESS` | Run browser in headless mode | true | No | | `LOG_LEVEL` | Logging level (DEBUG, INFO, WARNING, ERROR) | INFO | No | *Either `SSH_KEY_PATH` or `SSH_PASSWORD` must be provided for authentication. ### SSH Key Setup (Recommended) 1. Generate SSH key pair (if you don't have one): ```bash ssh-keygen -t ed25519 -C "your-email@example.com" ``` 2. Copy public key to remote server: ```bash ssh-copy-id user@remote-server ``` 3. Set `SSH_KEY_PATH` to the path of your private key (e.g., `~/.ssh/id_ed25519`) ## 🏃‍♂️ Running the Server ### Development Mode ```bash python linux_mcp_server.py ``` ### Testing the Server You can test the MCP protocol directly: ```bash echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python linux_mcp_server.py ``` ## 🤖 Claude Desktop Integration Add the server to your Claude Desktop configuration: **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` **Linux:** `~/.config/Claude/claude_desktop_config.json` ```json { "mcpServers": { "linux-server": { "command": "python", "args": ["/path/to/linux_mcp_server.py"], "env": { "SSH_HOST": "your-server.com", "SSH_USER": "your-username", "SSH_KEY_PATH": "/path/to/your/key", "BROWSER_HEADLESS": "true" } } } } ``` ## 🛠️ Available Tools ### Command Execution Tools #### `execute_command` Execute a single terminal command on the remote Linux server. ```python await execute_command("ls -la /home") ``` #### `execute_script` Execute a bash script with optional arguments. ```python await execute_script("/path/to/script.sh", "--verbose") ``` #### `create_bash_script` Create and deploy a new bash script to the remote server. ```python await create_bash_script("hello.sh", "echo 'Hello World'") ``` ### File System Tools #### `list_directory` List directory contents with detailed information. ```python await list_directory("/var/log") ``` ### System Monitoring Tools #### `get_system_info` Get comprehensive system information (CPU, memory, disk usage). ```python await get_system_info() ``` ### Browser Automation Tools #### `puppeteer_navigate` Navigate browser to a URL. ```python await puppeteer_navigate("https://example.com") ``` #### `puppeteer_screenshot` Capture screenshot of page or element. ```python await puppeteer_screenshot("homepage", "", "1200", "800") ``` #### `puppeteer_click` Click on a web page element. ```python await puppeteer_click("#submit-button") ``` #### `puppeteer_hover` Hover over a web page element. ```python await puppeteer_hover(".menu-item") ``` #### `puppeteer_fill` Fill a form input field. ```python await puppeteer_fill("#username", "myusername") ``` #### `puppeteer_select` Select an option from a dropdown. ```python await puppeteer_select("#country", "US") ``` #### `puppeteer_evaluate` Execute JavaScript in browser context. ```python await puppeteer_evaluate("document.title") ``` #### `puppeteer_get_console_logs` Get browser console logs. ```python await puppeteer_get_console_logs() ``` #### `puppeteer_get_screenshot` Get current browser screenshot. ```python await puppeteer_get_screenshot() ``` #### `puppeteer_get_network_details` Get network request details. ```python await puppeteer_get_network_details() ``` ## 📊 MCP Resources ### `console://logs` Access browser console output. ```python # Access via MCP resource API ``` ### `screenshot://current` Get current browser screenshot as base64. ```python # Access via MCP resource API ``` ### `network://details` Get network request/response data as JSON. ```python # Access via MCP resource API ``` ## 🔒 Security Considerations ### SSH Security - Use SSH key authentication instead of passwords when possible - Ensure SSH keys have proper permissions (600) - Regularly rotate SSH keys - Use SSH config for host-specific settings ### Command Execution Security - All commands are validated before execution - Timeout protection prevents hanging commands - Output is sanitized and truncated for safety - No shell injection vulnerabilities ### Browser Security - Headless mode prevents visible attacks - Isolated browser sessions per server instance - Network monitoring for security analysis - JavaScript execution in sandboxed environment ## 🐛 Troubleshooting ### SSH Connection Issues ``` ❌ Error: SSH connection failed ``` - Verify SSH credentials and server accessibility - Test manual SSH connection: `ssh user@host` - Check firewall settings and port accessibility - Ensure SSH key has correct permissions ### Browser Automation Issues ``` ❌ Error: Browser initialization failed ``` - Install Chrome/Chromium browser - Ensure sufficient system resources - Check headless mode compatibility - Verify browser dependencies ### Command Execution Timeouts ``` ⏱️ Command timed out ``` - Increase timeout values for long-running commands - Check server performance and resource usage - Verify command syntax and server responsiveness ## 📝 Usage Examples ### System Administration ``` "Check the disk usage on my server" "Show me the running processes sorted by CPU usage" "List all files in /var/log modified in the last day" ``` ### Web Automation ``` "Navigate to https://example.com and take a screenshot" "Fill out the login form with username 'admin' and password 'secret'" "Click the submit button and check for any console errors" ``` ### Network Monitoring ``` "Check what HTTP requests the page is making" "Monitor network activity while navigating between pages" "Capture console logs during form submission" ``` ## 🧪 Testing ### Unit Tests ```bash python -m pytest tests/ -v ``` ### Integration Tests ```bash python test_integration.py ``` ### Manual Testing Use the MCP Inspector tool for interactive testing: ```bash npx @modelcontextprotocol/inspector python linux_mcp_server.py ``` ## 🤝 Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests for new functionality 5. Submit a pull request ## 📄 License This project is licensed under the MIT License - see the LICENSE file for details. ## 🙏 Acknowledgments - Built with the [Model Context Protocol](https://modelcontextprotocol.io/) - Uses [Paramiko](https://www.paramiko.org/) for SSH - Uses [Pyppeteer](https://github.com/pyppeteer/pyppeteer) for browser automation - Inspired by various MCP server implementations in the ecosystem --- **Made with ❤️ for the AI and Linux communities**