Linux MCP Server

A read-only MCP (Model Context Protocol) server for Linux host observability and alert dispatch.

Features

• Host Identity: Get hostname, machine ID, kernel, OS info, and uptime
• System Metrics: CPU, memory, disk, and load metrics
• Process/Service Health: Check process existence, top processes, and systemd service status
• Log Sampling: Recent logs, pattern search, and log rate calculations
• Filesystem Signals: File existence, stats, and tail operations
• Network Monitoring: Port listening status and TCP connectivity checks
• Alert Sink: Send structured alerts to external endpoints

Security

This server is designed with security-first principles:

• Read-only: No system state modification
• Path Allowlisting: Only safe paths can be accessed
• Input Validation: All inputs are validated and sanitized
• Timeouts: Operations have configurable timeouts
• Output Limits: Maximum output size and line limits enforced

Installation

# Install from source
pip install -e .

# Or install dependencies manually
pip install mcp[cli]>=1.9.2 pydantic>=2.0.0 psutil>=5.9.0 httpx>=0.25.0

# Optional: systemd support
pip install systemd-python>=234

Usage

Basic Usage

# Run the server
uv run linux_mcp_server.py

# Or using the installed command
linux-mcp-server

With MCP Inspector

# Test with MCP inspector
mcp dev linux_mcp_server.py

With Claude Desktop

Add to your Claude Desktop config:

{
  "mcpServers": {
    "linux-observability": {
      "command": "uv",
      "args": ["run", "/path/to/linux_mcp_server.py"],
      "env": {
        "ALERT_ENDPOINT": "https://your-alert-endpoint.com/webhook"
      }
    }
  }
}

Available Tools

System Overview (Recommended Starting Point)

• system_overview() - Comprehensive system snapshot with health indicators, resource usage, and alerts

Host Identity

• host_info() - Get host metadata
• host_uptime() - Get uptime information

Metrics

• metrics_cpu() - CPU usage and core count
• metrics_memory() - Memory and swap usage
• metrics_disk(mounts?) - Disk usage by mount point
• metrics_load() - System load averages

Process & Service

• process_exists(name) - Check if process exists
• process_top(sort_by, limit) - Get top processes by CPU/memory
• service_status(name) - Get systemd service status
• process_diagnostics() - Zombie processes, file descriptor usage, thread counts

Logs

• logs_recent(source, path?, since_seconds, max_lines, unit?) - Get recent log entries (supports systemd unit filtering)
• logs_search(source, path?, pattern, since_seconds, max_matches) - Search logs
• logs_rate(source, path?, pattern, window_seconds) - Calculate log rate

Filesystem

• fs_exists(path) - Check if path exists
• fs_stat(path) - Get file/directory stats
• fs_tail(path, lines) - Get last N lines from file

Network

• net_port_listen(port) - Check if port is listening
• net_check_tcp(host, port, timeout_ms) - Test TCP connectivity
• net_dns_resolve(hostname, record_type?) - DNS resolution with latency measurement
• net_connections(state?, limit?) - Active network connections with process info

Network Interfaces

• network_interfaces() - Network interface status, routing, and statistics

Containers

• container_status() - Docker/Podman container status and health

Alerts

• alert_send(severity, summary, host?, tags?, payload?) - Send alert

Thermal Monitoring

• thermal_info() - CPU/GPU temperatures and fan speeds

Security Audit

• security_audit() - Security status and recent events

Storage Health

• smart_status(device?) - SMART disk health analysis

Package Updates

• package_updates() - Available system and security updates

Hardware Health

• hardware_health() - Overall hardware health assessment

Configuration

Environment Variables

• ALERT_ENDPOINT - HTTP endpoint for alert sink (optional)
• PYTHONPATH - Ensure the package is importable

Security Paths

The server allows read-only access to these paths:

• /var/log - Log files
• /proc - Process information
• /sys - System information
• /etc/os-release - OS information
• /etc/machine-id - Machine identifier
• /var/run - Runtime files
• /tmp - Temporary files

Response Format

All responses follow the JSON wrapper format specified in the design:

Success Response

{
  "ok": true,
  "data": { ... }
}

Error Response

{
  "ok": false,
  "error": {
    "code": "TIMEOUT|PERMISSION_DENIED|NOT_FOUND|INVALID_INPUT|INTERNAL",
    "message": "Human-readable explanation"
  }
}

Development

Project Structure

linux-mcp-server/
├── pyproject.toml              # Dependencies and config
├── linux_mcp_server.py        # Main entry point with PEP723 deps
├── opencode.json              # OpenCode MCP configuration
├── linux_mcp_server/          # Package
│   ├── server.py              # MCP server setup
│   ├── response.py            # JSON response wrappers
│   ├── security.py            # Security constraints
│   └── tools/                 # Tool implementations
│       ├── host.py           # Host identity
│       ├── metrics.py        # System metrics
│       ├── process.py        # Process/service health
│       ├── logs.py           # Log sampling
│       ├── filesystem.py     # Filesystem signals
│       ├── network.py        # Network tools
│       ├── alert.py          # Alert sink
│       ├── thermal.py        # Temperature monitoring
│       ├── security.py       # Security audit
│       ├── smart.py         # Storage health
│       ├── interfaces.py     # Network monitoring
│       ├── packages.py      # Package updates
│       └── hardware.py      # Hardware health

Adding New Tools

1. Create a new file in linux_mcp_server/tools/
2. Use the @server.tool() decorator
3. Return standardized responses using success() and error()
4. Import the module in linux_mcp_server/server.py

Testing

# Test with MCP inspector
mcp dev linux_mcp_server.py

# Test individual tools (example)
uv run -c "
from linux_mcp_server.tools.host import host_info
import json
print(json.dumps(host_info(), indent=2))
"

License

MIT License - see LICENSE file for details.