Linux MCP Server
Provides read-only diagnostic and troubleshooting tools for Linux systems, including system information, service management, process monitoring, log analysis, network diagnostics, and storage analysis on RHEL-based systems via local or remote SSH execution
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Linux MCP Server check disk usage on the remote production server"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:noneKey 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, uptimeget_cpu_info- CPU details and load averagesget_memory_info- RAM usage and swap detailsget_disk_usage- Filesystem usage and mount pointsget_hardware_info- Hardware details (CPU architecture, PCI/USB devices, memory hardware)
Service Management
list_services- List all systemd services with statusget_service_status- Detailed status of a specific serviceget_service_logs- Recent logs for a specific service
Process Management
list_processes- Running processes with CPU/memory usageget_process_info- Detailed information about a specific process
Logs & Audit
get_journal_logs- Query systemd journal with filtersget_audit_logs- Read audit logs (if available)read_log_file- Read specific log file (whitelist-controlled)
Network Diagnostics
get_network_interfaces- Network interface informationget_network_connections- Active network connectionsget_listening_ports- Ports listening on the system
Storage & Disk Analysis
list_block_devices- Block devices and partitionslist_directories_by_size- List directories sorted by size (largest first) with top N limitlist_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
Clone the repository:
git clone <repository-url>
cd linux-mcp-serverCreate 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.logJSON format:
~/.local/share/linux-mcp-server/logs/server.jsonRotated files:
server.log.YYYY-MM-DDandserver.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 detailsINFO: Tool calls, command executions, connection events, operation resultsWARNING: Authentication failures, retryable errors, missing optional dataERROR: Failed operations, exceptions, connection failuresCRITICAL: 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 useLINUX_MCP_SSH_KEY_PATHConnection 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-serverUsing uvx (recommended for one-off execution without installation):
uvx --from /path/to/linux-mcp-server linux-mcp-serverTraditional Python module execution:
python -m linux_mcp_serverUsing 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
pytestRunning Tests with Coverage
pytest --cov=src --cov-report=htmlSecurity 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 toolsget_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
Scored across 20 tools
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.
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.
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.
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
Read-only server insight: why a Linux server or K8s cluster is slow, failing or changed.
Read-only Linux server and Docker monitoring for AI assistants: CPU, memory, disk, network.
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Linux package, file, command, vulnerability, lifecycle, migration, and repository intelligence.
Related MCP Servers
- AlicenseAqualityFmaintenanceEnables 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.20MIT
- AlicenseBqualityAmaintenanceAn 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.23510 PyPI323Apache 2.0
- FlicenseNot gradedqualityDmaintenanceEnables managing Linux servers via SSH with tools for command execution, file operations, service management, and log analysis.-
- AlicenseBqualityFmaintenanceEnables explaining Linux incidents over SSH with baseline-aware MCP tooling, including live diagnostics, SQLite history, and review-first workflows.10287 npm2MIT