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:

pip install -r requirements.txt

2. Create environment file:

cp .env.example .env

3. Edit .env with your credentials:

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

ssh-keygen -t rsa -b 4096 -f ~/.ssh/linux_mcp_key

2. Copy public key to target host:

ssh-copy-id -i ~/.ssh/linux_mcp_key.pub username@your-server-ip

3. Set the key path in .env:

LINUX_SSH_KEY_PATH=/home/user/.ssh/linux_mcp_key

Running the Server

Directly with your system python:

python linux_mcp_server.py

Directly with your virtual environment python in uv:

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:

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

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

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

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

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.