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

Clone or create the project directory:

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

Install dependencies:
```
pip install -r requirements.txt
```

Configure environment variables:

cp config.example.env .env
# Edit .env with your SSH and configuration settings

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)

Generate SSH key pair (if you don't have one):

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

Copy public key to remote server:
```
ssh-copy-id user@remote-server
```
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

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
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