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

*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

Testing the Server

You can test the MCP protocol directly:

🤖 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

🛠️ Available Tools

Command Execution Tools

execute_command

Execute a single terminal command on the remote Linux server.

execute_script

Execute a bash script with optional arguments.

create_bash_script

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

File System Tools

list_directory

List directory contents with detailed information.

System Monitoring Tools

get_system_info

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

Browser Automation Tools

puppeteer_navigate

Navigate browser to a URL.

puppeteer_screenshot

Capture screenshot of page or element.

puppeteer_click

Click on a web page element.

puppeteer_hover

Hover over a web page element.

puppeteer_fill

Fill a form input field.

puppeteer_select

Select an option from a dropdown.

puppeteer_evaluate

Execute JavaScript in browser context.

puppeteer_get_console_logs

Get browser console logs.

puppeteer_get_screenshot

Get current browser screenshot.

puppeteer_get_network_details

Get network request details.

📊 MCP Resources

console://logs

Access browser console output.

screenshot://current

Get current browser screenshot as base64.

network://details

Get network request/response data as JSON.

🔒 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

• 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

• Install Chrome/Chromium browser

• Ensure sufficient system resources

• Check headless mode compatibility

• Verify browser dependencies

Command Execution Timeouts

• Increase timeout values for long-running commands

• Check server performance and resource usage

• Verify command syntax and server responsiveness

📝 Usage Examples

System Administration

Web Automation

Network Monitoring

🧪 Testing

Unit Tests

Integration Tests

Manual Testing

Use the MCP Inspector tool for interactive testing:

🤝 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