# Linux MCP Server Setup Guide

This MCP server allows you to execute Linux commands on remote hosts securely via SSH.

## Features

- **Execute arbitrary Linux commands** on remote hosts
- **System information gathering** (hostname, OS, memory, disk usage, etc.)
- **Directory listing** with detailed options
- **File operations** (read, write, append)
- **Secure authentication** via SSH keys or passwords
- **Environment-based configuration** for credentials
- **Connection management** with automatic reconnection

## Installation

1. **Install dependencies:**
```bash
pip install -r requirements.txt
```

2. **Create environment file:**
```bash
cp .env.example .env
```

3. **Edit `.env` with your credentials:**
```bash
# Required settings
LINUX_HOST=your-server-ip
LINUX_USERNAME=your-username

# Authentication: Use either password OR SSH key (SSH key is recommended)
# Option 1: Password authentication
LINUX_PASSWORD=your_password

# Option 2: SSH key authentication (recommended)
LINUX_SSH_KEY_PATH=/path/to/your/private/key

# Optional: Connection timeout in seconds
LINUX_TIMEOUT=30

# Optional: Logging level (DEBUG, INFO, WARNING, ERROR)
LOG_LEVEL=INFO

# Enable/disable warnings (default: true)
LINUX_ENABLE_WARNINGS=true

# Block critical commands entirely (default: false)  
LINUX_BLOCK_CRITICAL=false

# Requires confirmation for high/critical commands (default: true)
# Disables confirmation requirement (only shows warnings) if false
LINUX_REQUIRE_CONFIRMATION=true
```

## Configuration Options

### Required Variables
- `LINUX_HOST`: IP address or hostname of the target Linux system
- `LINUX_USERNAME`: Username for SSH connection

### Authentication (choose one)
- `LINUX_SSH_KEY_PATH`: Path to your SSH private key file (recommended)
- `LINUX_PASSWORD`: SSH password (less secure)

### Optional Variables
- `LINUX_PORT`: SSH port (default: 22)
- `LINUX_TIMEOUT`: Connection timeout in seconds (default: 30)
- `LOG_LEVEL`: Logging level (default: INFO)
- `LINUX_ENABLE_WARNINGS`: Enable/disable warnings (default: true)
- `LINUX_BLOCK_CRITICAL`: Block critical commands entirely (default: false)  
- `LINUX_REQUIRE_CONFIRMATION`: Requires confirmation for high/critical commands (default: true). Else, disables confirmation requirement (only shows warnings) - ⚠️⚠️⚠️ DANGEROUS!!! ⚠️⚠️⚠️

## Important Configuration Notice

> **Warning:** The Linux MCP server supports configuration changes and potential execution of critial commands, but please ensure you only use this functionality when you want LLM-generated configurations to be loaded and/or potential critical commands executed on your linux server.

**Always review the configuration being generated or the commands being executed by the LLM 
and only allow tool execution if it's the correct configuration/execution for your use case.**

## SSH Key Setup (Recommended)

1. **Generate SSH key pair (if you don't have one):**
```bash
ssh-keygen -t rsa -b 4096 -f ~/.ssh/linux_mcp_key
```

2. **Copy public key to target host:**
```bash
ssh-copy-id -i ~/.ssh/linux_mcp_key.pub username@your-server-ip
```

3. **Set the key path in .env:**
```bash
LINUX_SSH_KEY_PATH=/home/user/.ssh/linux_mcp_key
```

## Running the Server

Directly with your system python:
```bash
python linux_mcp_server.py
```

Directly with your virtual environment python in `uv`:
```bash
uv run python linux_mcp_server.py
```

## Available Tools

### 1. execute_command
Execute any Linux command on the remote host.
- **Parameters:**
  - `command` (required): The Linux command to execute
  - `timeout` (optional): Command timeout in seconds

**Example:**
```json
{
  "command": "ps aux | grep python",
  "timeout": 60
}
```

### 2. get_system_info
Get comprehensive system information including hostname, OS, memory, disk usage, and CPU info.

**Example usage:** No parameters required.

### 3. list_directory
List contents of a directory.
- **Parameters:**
  - `path` (optional): Directory path (default: current directory)
  - `detailed` (optional): Show detailed listing with permissions, sizes, etc.

**Example:**
```json
{
  "path": "/var/log",
  "detailed": true
}
```

### 4. file_operations
Perform file read/write operations.
- **Parameters:**
  - `operation` (required): "read", "write", or "append"
  - `file_path` (required): Path to the file
  - `content` (required for write/append): Content to write/append

**Example:**
```json
{
  "operation": "write",
  "file_path": "/tmp/test.txt",
  "content": "Hello, World!"
}
```

## Security Considerations

1. **Use SSH keys instead of passwords** when possible
2. **Limit user permissions** on the target host
3. **Use a dedicated user** for MCP operations
4. **Keep your .env file secure** and never commit it to version control
5. **Consider firewall rules** to restrict SSH access
6. **Regular key rotation** for enhanced security

## Troubleshooting

### Connection Issues
- Verify host IP and port are correct
- Check if SSH service is running on target host
- Ensure firewall allows SSH connections
- Verify SSH key permissions (should be 600)

### Authentication Issues
- Check username is correct
- For SSH keys: ensure public key is in `~/.ssh/authorized_keys` on target host
- For passwords: verify password is correct and account is not locked

### Permission Issues
- Ensure the user has necessary permissions for the commands you're trying to execute
- Consider using `sudo` in commands if needed (configure sudoers appropriately)

## Example .env File

```bash
# Production server
LINUX_HOST=192.168.1.100
LINUX_PORT=22
LINUX_USERNAME=mcpuser
LINUX_SSH_KEY_PATH=/home/user/.ssh/production_key
LINUX_TIMEOUT=30
LOG_LEVEL=INFO
LINUX_ENABLE_WARNINGS=true
LINUX_BLOCK_CRITICAL=true
LINUX_REQUIRE_CONFIRMATION=true
```

## Integration with MCP Clients

This server follows the MCP (Model Context Protocol) specification and can be integrated with any MCP-compatible client. The server communicates via stdio and provides structured tool definitions that clients can discover and use.

## Security

Maximum Safety Configuration Successfully intented. The Linux MCP server is configured with maximum safety settings:

```bash
Configuration Applied:
Environment Variables Set:

LINUX_ENABLE_WARNINGS=true          # Show all warnings
LINUX_BLOCK_CRITICAL=true           # Block critical commands entirely  
LINUX_REQUIRE_CONFIRMATION=true     # Require confirmation for dangerous commands
```

### Safety Behavior Now Active:

#### 🛡️ Critical Commands (rm -rf /, dd of=/dev/, etc.)**

COMPLETELY BLOCKED - Cannot be executed even with confirmation
Will show error message explaining the block

#### ⚠️ High-Risk Commands (shutdown, reboot, kill, etc.)

REQUIRES CONFIRMATION - Must ask user first, then re-run with confirm_dangerous=true
Shows detailed warnings about risks

#### ⚡ Medium-Risk Commands (chmod, docker, etc.)

SHOWS WARNINGS - Executes with safety warnings displayed

#### ✅ Safe Commands

Execute normally without warnings

What This Means:

I will ALWAYS ask for confirmation before running dangerous commands like shutdown, reboot, kill, etc.
Critical commands will be completely blocked - commands like rm -rf /, dd of=/dev/sda, mkfs cannot be executed at all
All warnings are enabled - you'll see detailed risk analysis for any potentially dangerous operation
The system is now maximally protected while still being functional for legitimate operations

The Linux MCP server is now configured with the highest level of safety protection possible. When the server restarts, it will load these new settings and enforce maximum safety protocols.