Overview

SystemSage is an MCP (Model Context Protocol) server that collects system-level telemetry and exposes management operations through a standardized protocol. It runs cross-platform and aggregates real-time metrics (CPU, memory, disk, network), process and service information, container and Kubernetes status, and basic security checks. By exposing these capabilities via MCP, SystemSage can be integrated into tooling that expects conversational or programmatic access to system context and actions.

For developers, SystemSage is useful when you need to query system state programmatically, build monitoring assistants, or provide safe remote management workflows. It centralizes common administrative tasks (process inspection, service control, disk health checks) behind a consistent API surface and supports optional cloud integrations for container and cluster visibility.

Features

Real-time CPU, memory and disk usage metrics
Live network interface and throughput reporting
Process discovery and detailed process inspection by PID or name
Start/stop/restart and status checks for system services
Docker container management and Kubernetes cluster monitoring (optional)
Disk SMART checks and basic disk health reporting
Environment variable and startup-program enumeration
Cleanup utilities (temporary files) and automated system health checks
Alerting and diagnostics (failed logins, open ports, resource anomalies)
Cross-platform support (Linux, macOS, Windows) with privilege-aware operations

Installation / Configuration

Quick install (recommended)

# Basic installation from PyPI
pip install systemsage

# Install with optional cloud/container integrations
pip install systemsage[cloud]

Run as a normal MCP server (examples)

# Run in-process with Python module
python -m SystemSage

# If you use uv / uvx to manage MCP servers
uvx systemsage@latest

Cursor Desktop MCP server examples

Using uvx

{
  "mcpServers": {
    "systemsage": {
      "command": "uvx",
      "args": ["systemsage@latest"]
    }
  }
}

Using Python

{
  "mcpServers": {
    "systemsage": {
      "command": "python",
      "args": ["-m", "SystemSage"]
    }
  }
}

Local debug (from cloned repo)

{
  "mcpServers": {
    "systemsage": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/SystemSage/",
        "run",
        "systemsage"
      ]
    }
  }
}

Available Tools

The server exposes a set of callable tools for telemetry and management. Typical signatures:

Tool	Description	Parameters
get_cpu_usage()	Current CPU usage (percentage)	None
get_memory_usage()	Memory usage and stats	None
get_disk_usage()	Disk usage by mount/partition	None
get_network_interfaces()	Network interface info and stats	None
monitor_system_resources(duration: int = 10)	Sample system metrics over time	duration (seconds)
get_process_details(pid: int)	Full details for a process	pid
find_processes_by_name(name: str)	Find processes matching pattern	name
get_system_alerts()	Aggregated alerts and detected issues	None
cleanup_temp_files()	Remove temporary files to free space	None
get_security_status()	Basic security checks (open ports, login failures)	None
get_startup_programs()	Programs configured to start on boot	None
check_disk_health()	SMART / disk health checks	None
get_environment_variables()	System environment variables	None
system_health_check()	Comprehensive health report and scoring	None
manage_docker_containers(action: str, container_name: str)	Docker container control (optional)	action, container_name

Use these tools via MCP calls or by integrating the Python module in local automation.

Use Cases

Troubleshooting high CPU or memory usage:
- Call get_cpu_usage() and find_processes_by_name() to identify the offending process, then use get_process_details(pid) to inspect threads and open files.
Remote safe service management:
- Query service status and then use service control actions (start/stop/restart) surfaced by SystemSage to perform maintenance with auditability.
Network and connectivity checks:
- Use get_network_interfaces() and a simple connectivity probe to verify outbound internet access before initiating cloud operations.
Container and cluster debugging:
- With cloud extras installed, enumerate Docker containers and basic Kubernetes pod statuses to spot unhealthy workloads.
Scheduled system health reports:
- Periodically run system_health_check() and log or forward the report to a monitoring pipeline to detect trends and regressions.

Example command sequence (Python-driven):

from systemsage import SystemSageClient

client = SystemSageClient()
print(client.get_cpu_usage())
procs = client.find_processes_by_name("java")
for p in procs:
    print(client.get_process_details(p["pid"]))

Requirements

Python 3.10+
psutil>=5.9.0
fastmcp>=1.0.0
click>=8.1.0

Optional for extended features:

requests (cloud API calls)
docker (Docker management)
kubernetes (K8s monitoring)

Security & Permissions

Many operations require elevated privileges (root/Administrator). Run with care.
SystemSage provides powerful controls (killing processes, modifying services). Test commands in non-production environments first.
Follow least-privilege practices: grant only required permissions to automation agents interacting with the MCP server.

Contributing

Contributions are welcome via GitHub. Fork the repo, create a feature branch, and open a pull request. Include tests and clear descriptions for behavioral changes.

SystemSage MCP Server for System Insights and Management