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

Architecture Overview

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:

2. Create virtual environment and install dependencies:

Configuration

Configure the server using environment variables:

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:

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:

Usage

Running the Server

You can run the server in multiple ways:

Using uv run (recommended for development):

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

Traditional Python module execution:

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

Option 2: Using uvx (from local directory):

Development

Running Tests

Running Tests with Coverage

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