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:

   mkdir awesome-linux-mcp
   cd awesome-linux-mcp
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Configure environment variables:

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

   ssh-keygen -t ed25519 -C "your-email@example.com"
   

2. Copy public key to remote server:

   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

python linux_mcp_server.py

Testing the Server

You can test the MCP protocol directly:

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

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

await execute_command("ls -la /home")

execute_script

Execute a bash script with optional arguments.

await execute_script("/path/to/script.sh", "--verbose")

create_bash_script

Create and deploy a new bash script to the remote server.

await create_bash_script("hello.sh", "echo 'Hello World'")

File System Tools

list_directory

List directory contents with detailed information.

await list_directory("/var/log")

System Monitoring Tools

get_system_info

Get comprehensive system information (CPU, memory, disk usage).

await get_system_info()

Browser Automation Tools

puppeteer_navigate

Navigate browser to a URL.

await puppeteer_navigate("https://example.com")

puppeteer_screenshot

Capture screenshot of page or element.

await puppeteer_screenshot("homepage", "", "1200", "800")

puppeteer_click

Click on a web page element.

await puppeteer_click("#submit-button")

puppeteer_hover

Hover over a web page element.

await puppeteer_hover(".menu-item")

puppeteer_fill

Fill a form input field.

await puppeteer_fill("#username", "myusername")

puppeteer_select

Select an option from a dropdown.

await puppeteer_select("#country", "US")

puppeteer_evaluate

Execute JavaScript in browser context.

await puppeteer_evaluate("document.title")

puppeteer_get_console_logs

Get browser console logs.

await puppeteer_get_console_logs()

puppeteer_get_screenshot

Get current browser screenshot.

await puppeteer_get_screenshot()

puppeteer_get_network_details

Get network request details.

await puppeteer_get_network_details()

📊 MCP Resources

console://logs

Access browser console output.

# Access via MCP resource API

screenshot://current

Get current browser screenshot as base64.

# Access via MCP resource API

network://details

Get network request/response data as JSON.

# 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

python -m pytest tests/ -v

Integration Tests

python test_integration.py

Manual Testing

Use the MCP Inspector tool for interactive testing:

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
• Uses Paramiko for SSH
• Uses Pyppeteer for browser automation
• Inspired by various MCP server implementations in the ecosystem

---

Made with ❤️ for the AI and Linux communities