Skip to main content
Glama
Linux MCP Server

Linux MCP Server

by narmaku

Linux MCP Server

A Model Context Protocol (MCP) server for read-only Linux system administration, diagnostics, and troubleshooting on RHEL-based systems.

Features

  • Read-Only Operations: All tools are strictly read-only for safe diagnostics

  • Remote SSH Execution: Execute commands on remote systems via SSH with key-based authentication

  • Multi-Host Management: Connect to different remote hosts in the same session

  • Comprehensive Diagnostics: System info, services, processes, logs, network, and storage

  • Configurable Log Access: Control which log files can be accessed via environment variables

  • RHEL/systemd Focused: Optimized for Red Hat Enterprise Linux systems

Related MCP server: Linux MCP Server

Architecture Overview

graph TB
    Client["Client Layer<br/>MCP Client (e.g. Claude Desktop)"]
    
    subgraph Server["MCP Server"]
        FastMCP[FastMCP Server]
        
        subgraph Tools["Tool Categories"]
            direction LR
            subgraph Row1[" "]
                SystemInfo[System Info]
                Services[Services]
                Processes[Processes]
            end
            subgraph Row2[" "]
            Logs[Logs & Audit]
                Network[Network]
                Storage[Storage]
            end
        end
        
        Executor[SSH Executor]
        Logger[Audit Logger]
    end
    
    subgraph Targets["Execution Targets"]
        direction LR
        Local[Local System]
        Remote[Remote Hosts<br/>SSH]
    end
    
    Client -->|MCP Protocol| FastMCP
    FastMCP --> Tools
    Tools --> Executor
    Executor --> Targets
    
    FastMCP -.-> Logger
    Executor -.-> Logger
    
    style Client fill:#4a9eff,stroke:#2563eb,color:#fff
    style FastMCP fill:#f59e0b,stroke:#d97706,color:#fff
    style SystemInfo fill:#64748b,stroke:#475569,color:#fff
    style Services fill:#64748b,stroke:#475569,color:#fff
    style Processes fill:#64748b,stroke:#475569,color:#fff
    style Logs fill:#64748b,stroke:#475569,color:#fff
    style Network fill:#64748b,stroke:#475569,color:#fff
    style Storage fill:#64748b,stroke:#475569,color:#fff
    style Executor fill:#10b981,stroke:#059669,color:#fff
    style Logger fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style Local fill:#eab308,stroke:#ca8a04,color:#fff
    style Remote fill:#eab308,stroke:#ca8a04,color:#fff
    style Row1 fill:none,stroke:none
    style Row2 fill:none,stroke:none

Key Components

  • FastMCP Server: Core MCP protocol server handling tool registration and invocation

  • Tool Categories: Six categories of read-only diagnostic tools (system info, services, processes, logs, network, storage)

  • SSH Executor: Routes commands to local subprocess or remote SSH execution with connection pooling

  • Audit Logger: Comprehensive logging in both human-readable and JSON formats with automatic rotation

  • Multi-Target Execution: Single server instance can execute commands on local system or multiple remote hosts

Available Tools

System Information

  • get_system_info - OS version, kernel, hostname, uptime

  • get_cpu_info - CPU details and load averages

  • get_memory_info - RAM usage and swap details

  • get_disk_usage - Filesystem usage and mount points

  • get_hardware_info - Hardware details (CPU architecture, PCI/USB devices, memory hardware)

Service Management

  • list_services - List all systemd services with status

  • get_service_status - Detailed status of a specific service

  • get_service_logs - Recent logs for a specific service

Process Management

  • list_processes - Running processes with CPU/memory usage

  • get_process_info - Detailed information about a specific process

Logs & Audit

  • get_journal_logs - Query systemd journal with filters

  • get_audit_logs - Read audit logs (if available)

  • read_log_file - Read specific log file (whitelist-controlled)

Network Diagnostics

  • get_network_interfaces - Network interface information

  • get_network_connections - Active network connections

  • get_listening_ports - Ports listening on the system

Storage & Disk Analysis

  • list_block_devices - Block devices and partitions

  • list_directories_by_size - List directories sorted by size (largest first) with top N limit

  • list_directories_by_name - List all directories sorted alphabetically (A-Z or Z-A)

  • list_directories_by_modified_date - List all directories sorted by modification date (newest/oldest first)

Installation

Prerequisites

  • Python 3.10 or higher

  • uv package manager

Setup

  1. Clone the repository:

git clone <repository-url>
cd linux-mcp-server
  1. Create virtual environment and install dependencies:

uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

Configuration

Configure the server using environment variables:

# Comma-separated list of allowed log file paths
export LINUX_MCP_ALLOWED_LOG_PATHS="/var/log/messages,/var/log/secure,/var/log/audit/audit.log"

# Optional: Set log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
export LINUX_MCP_LOG_LEVEL="INFO"

# Optional: Custom log directory (default: ~/.local/share/linux-mcp-server/logs/)
export LINUX_MCP_LOG_DIR="/var/log/linux-mcp-server"

# Optional: Log retention in days (default: 10)
export LINUX_MCP_LOG_RETENTION_DAYS="30"

# Optional: Specify SSH private key path (defaults to ~/.ssh/id_ed25519, ~/.ssh/id_rsa, etc.)
export LINUX_MCP_SSH_KEY_PATH="/path/to/your/private/key"

Audit Logging

The server includes comprehensive audit logging for all operations:

Features:

  • Dual Format: Logs written in both human-readable text and JSON formats

  • Daily Rotation: Automatic log rotation at midnight

  • Configurable Retention: Keep logs for a specified number of days (default: 10)

  • Tiered Verbosity: INFO for operations, DEBUG for detailed diagnostics

  • Sanitization: Automatic redaction of sensitive data (passwords, tokens, API keys)

Log Files:

  • Human-readable: ~/.local/share/linux-mcp-server/logs/server.log

  • JSON format: ~/.local/share/linux-mcp-server/logs/server.json

  • Rotated files: server.log.YYYY-MM-DD and server.json.YYYY-MM-DD

What Gets Logged:

  • Server startup and shutdown

  • All tool invocations with parameters (sanitized)

  • Tool execution time and completion status

  • SSH connections (success/failure)

  • Remote command execution

  • Error conditions with full context

Log Levels:

  • DEBUG: Detailed flow, connection reuse, function entry/exit, timing details

  • INFO: Tool calls, command executions, connection events, operation results

  • WARNING: Authentication failures, retryable errors, missing optional data

  • ERROR: Failed operations, exceptions, connection failures

  • CRITICAL: Server startup/shutdown failures, unrecoverable errors

Example Log Entries:

# Human-readable format (server.log)
2025-10-10 14:23:45.123 | INFO | server | TOOL_CALL: list_services | host=server1.example.com | username=admin | execution_mode=remote
2025-10-10 14:23:45.234 | INFO | ssh_executor | SSH_CONNECT: admin@server1.example.com | status=success
2025-10-10 14:23:45.345 | INFO | ssh_executor | REMOTE_EXEC: systemctl list-units --type=service | host=server1.example.com | exit_code=0
2025-10-10 14:23:45.456 | INFO | server | TOOL_COMPLETE: list_services | status=success | duration=0.333s

# JSON format (server.json)
{"timestamp": "2025-10-10T14:23:45.123Z", "level": "INFO", "logger": "server", "message": "TOOL_CALL: list_services", "event": "TOOL_CALL", "tool": "list_services", "host": "server1.example.com", "username": "admin", "execution_mode": "remote"}

Remote SSH Execution

All tools support optional host and username parameters for remote execution via SSH:

  • Authentication: SSH key-based authentication only (no password support)

  • Key Discovery: Automatically discovers SSH keys from ~/.ssh/ or use LINUX_MCP_SSH_KEY_PATH

  • Connection Pooling: Reuses SSH connections for efficiency

  • Multi-Host: Each tool call can target a different remote host

Requirements:

  • SSH key-based authentication must be configured on remote hosts

  • Remote user must have appropriate permissions for diagnostic commands

Example Usage:

# Local execution
await list_services()

# Remote execution
await list_services(host="server1.example.com", username="admin")

# Different host in same session
await get_service_status("nginx", host="server2.example.com", username="sysadmin")

Usage

Running the Server

You can run the server in multiple ways:

Using uv run (recommended for development):

uv run linux-mcp-server

Using uvx (recommended for one-off execution without installation):

uvx --from /path/to/linux-mcp-server linux-mcp-server

Traditional Python module execution:

python -m linux_mcp_server

Using with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Option 1: Using uv run (simpler):

{
  "mcpServers": {
    "linux-diagnostics": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/linux-mcp-server",
        "run",
        "linux-mcp-server"
      ],
      "env": {
        "LINUX_MCP_ALLOWED_LOG_PATHS": "/var/log/messages,/var/log/secure,/var/log/audit/audit.log"
      }
    }
  }
}

Option 2: Using uvx (from local directory):

{
  "mcpServers": {
    "linux-diagnostics": {
      "command": "uvx",
      "args": [
        "--from",
        "/path/to/linux-mcp-server",
        "linux-mcp-server"
      ],
      "env": {
        "LINUX_MCP_ALLOWED_LOG_PATHS": "/var/log/messages,/var/log/secure,/var/log/audit/audit.log"
      }
    }
  }
}

Development

Running Tests

pytest

Running Tests with Coverage

pytest --cov=src --cov-report=html

Security Considerations

  • All operations are read-only

  • Log file access is controlled via whitelist (LINUX_MCP_ALLOWED_LOG_PATHS)

  • SSH key-based authentication only - no password support

  • SSH host key verification is disabled for flexibility (use with caution)

  • No arbitrary command execution

  • Input validation on all parameters

  • Requires appropriate system permissions for diagnostics

  • Remote user needs proper sudo/permissions for privileged commands

License

MIT License

Available Tools

20 tools
get_audit_logsC

Get audit logs if available.

Args:
    lines: Number of log lines to retrieve (default: 100)
    host: Remote host to connect to via SSH (optional, executes locally if not provided)
    username: SSH username for remote host (required if host is provided)

Inputs: lines, host, username. Returns: result

get_cpu_infoB

Get CPU information and load averages.

Args:
    host: Remote host to connect to via SSH (optional, executes locally if not provided)
    username: SSH username for remote host (required if host is provided)

Inputs: host, username. Returns: result

get_disk_usageB

Get filesystem usage and mount points.

Args:
    host: Remote host to connect to via SSH (optional, executes locally if not provided)
    username: SSH username for remote host (required if host is provided)

Inputs: host, username. Returns: result

get_hardware_infoB

Get hardware information including CPU architecture, PCI devices, USB devices, and memory hardware.

Args:
    host: Remote host to connect to via SSH (optional, executes locally if not provided)
    username: SSH username for remote host (required if host is provided)

Inputs: host, username. Returns: result

get_journal_logsA

Query systemd journal logs with optional filters.

Args:
    unit: Filter by systemd unit
    priority: Filter by priority (emerg, alert, crit, err, warning, notice, info, debug)
    since: Show entries since specified time (e.g., '1 hour ago', '2024-01-01')
    lines: Number of log lines to retrieve (default: 100)
    host: Remote host to connect to via SSH (optional, executes locally if not provided)
    username: SSH username for remote host (required if host is provided)

Inputs: unit, priority, since, lines, +2 more. Returns: result

get_listening_portsB

Get ports that are listening on the system.

Args:
    host: Remote host to connect to via SSH (optional, executes locally if not provided)
    username: SSH username for remote host (required if host is provided)

Inputs: host, username. Returns: result

get_memory_infoB

Get memory usage including RAM and swap details.

Args:
    host: Remote host to connect to via SSH (optional, executes locally if not provided)
    username: SSH username for remote host (required if host is provided)

Inputs: host, username. Returns: result

get_network_connectionsB

Get active network connections.

Args:
    host: Remote host to connect to via SSH (optional, executes locally if not provided)
    username: SSH username for remote host (required if host is provided)

Inputs: host, username. Returns: result

get_network_interfacesB

Get network interface information including IP addresses.

Args:
    host: Remote host to connect to via SSH (optional, executes locally if not provided)
    username: SSH username for remote host (required if host is provided)

Inputs: host, username. Returns: result

get_process_infoB

Get detailed information about a specific process.

Args:
    pid: Process ID
    host: Remote host to connect to via SSH (optional, executes locally if not provided)
    username: SSH username for remote host (required if host is provided)

Inputs: pid (required), host, username. Returns: result

get_service_logsA

Get recent logs for a specific systemd service.

Args:
    service_name: Name of the service
    lines: Number of log lines to retrieve (default: 50)
    host: Remote host to connect to via SSH (optional, executes locally if not provided)
    username: SSH username for remote host (required if host is provided)

Inputs: service_name (required), lines, host, username. Returns: result

get_service_statusB

Get detailed status of a specific systemd service.

Args:
    service_name: Name of the service
    host: Remote host to connect to via SSH (optional, executes locally if not provided)
    username: SSH username for remote host (required if host is provided)

Inputs: service_name (required), host, username. Returns: result

get_system_infoA

Get basic system information including OS version, kernel, hostname, and uptime.

Args:
    host: Remote host to connect to via SSH (optional, executes locally if not provided)
    username: SSH username for remote host (required if host is provided)

Inputs: host, username. Returns: result

list_block_devicesA

List block devices and partitions.

Args:
    host: Remote host to connect to via SSH (optional, executes locally if not provided)
    username: SSH username for remote host (required if host is provided)

Inputs: host, username. Returns: result

list_directories_by_modified_dateA

List directories sorted by modification date. Uses efficient Linux find command.

Args:
    path: Directory path to analyze
    newest_first: Show newest first (default: True)
    host: Remote host to connect to via SSH (optional, executes locally if not provided)
    username: SSH username for remote host (required if host is provided)

Inputs: path (required), newest_first, host, username. Returns: result

list_directories_by_nameA

List directories sorted alphabetically by name. Uses efficient Linux find command.

Args:
    path: Directory path to analyze
    reverse: Sort in reverse order (Z-A) (default: False)
    host: Remote host to connect to via SSH (optional, executes locally if not provided)
    username: SSH username for remote host (required if host is provided)

Inputs: path (required), reverse, host, username. Returns: result

list_directories_by_sizeA

List directories sorted by size (largest first). Uses efficient Linux du command.

Args:
    path: Directory path to analyze
    top_n: Number of top largest directories to return (1-1000)
    host: Remote host to connect to via SSH (optional, executes locally if not provided)
    username: SSH username for remote host (required if host is provided)

Inputs: path (required), top_n (required), host, username. Returns: result

list_processesA

List running processes with CPU and memory usage.

Args:
    host: Remote host to connect to via SSH (optional, executes locally if not provided)
    username: SSH username for remote host (required if host is provided)

Inputs: host, username. Returns: result

list_servicesA

List all systemd services with their current status.

Args:
    host: Remote host to connect to via SSH (optional, executes locally if not provided)
    username: SSH username for remote host (required if host is provided)

Inputs: host, username. Returns: result

read_log_fileA

Read a specific log file (whitelist-controlled via LINUX_MCP_ALLOWED_LOG_PATHS).

Args:
    log_path: Path to the log file
    lines: Number of lines to retrieve from the end (default: 100)
    host: Remote host to connect to via SSH (optional, executes locally if not provided)
    username: SSH username for remote host (required if host is provided)

Inputs: log_path (required), lines, host, username. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 20 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose targeting specific Linux system components or operations. Tools like get_cpu_info, get_memory_info, and get_disk_usage focus on different system resources, while list_directories_by_modified_date, list_directories_by_name, and list_directories_by_size offer distinct sorting methods for directory listings. No significant overlap exists between tools.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with snake_case throughout. The naming convention is highly predictable: 'get_' for retrieval operations, 'list_' for enumeration, and 'read_' for file reading. This consistency makes the tool set easy to navigate and understand.

    Tool Count4/5

    With 20 tools, the count is slightly high but reasonable for a comprehensive Linux system monitoring and management server. The tools cover various system aspects (CPU, memory, disk, network, processes, services, logs), which justifies the number, though it borders on being heavy for some use cases.

    Completeness4/5

    The tool set provides excellent coverage for monitoring and querying Linux system state, including hardware, processes, services, logs, and network information. Minor gaps exist, such as the lack of tools for modifying system state (e.g., starting/stopping services, killing processes) or file operations beyond log reading, but core read-only operations are well-covered.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      F
      maintenance
      Enables read-only Linux system diagnostics and troubleshooting on RHEL-based systems, including system info, services, processes, logs, network, and storage analysis. Supports both local and remote SSH execution across multiple hosts.
      20
      MIT
    • A
      license
      B
      quality
      A
      maintenance
      An MCP server for read-only Linux system administration and diagnostics on RHEL-based systems via SSH. It enables users to troubleshoot remote hosts by accessing system information, services, logs, and network configurations through natural language.
      23
      510 PyPI
      323
      Apache 2.0
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables managing Linux servers via SSH with tools for command execution, file operations, service management, and log analysis.
      -