sysops-mcp

An MCP server that gives AI assistants safe, read-only visibility into a host: CPU, memory, disk, processes, network, ports, and logs.

Built for the kind of first-pass triage an on-call engineer does before deciding whether a box needs attention. Ask your assistant "how is this server doing?" and it can actually go look.

You: hey, the app feels slow, can you check the box?

Assistant: [get_host_summary] -> CPU 4%, RAM 91%, swap 88%, fullest disk 62%
                                 "memory is nearly exhausted"
           [list_top_processes sort_by=memory] -> postgres using 71% RAM
           [tail_log /var/log/postgresql/postgresql.log grep="checkpoint"]

           Memory is the pressure point, not CPU. Postgres is holding 71% of
           RAM and the logs show frequent checkpoints...

Tools

Tool	What it does
get_host_summary	One-call health snapshot: uptime, CPU, RAM, swap, fullest disk, plain-language assessment. The right first call.
get_cpu_status	Utilization (configurable sample window), core counts, load averages, load-per-core saturation check.
get_memory_status	RAM and swap usage.
get_disk_usage	Per-partition usage with a configurable warning threshold. Read-only mounts are listed but never flagged.
list_top_processes	Top N processes by CPU or memory, with name filtering.
get_network_status	Interfaces, addresses, I/O totals, optional TCP connection states.
check_port	TCP connect test with latency, distinguishing refused vs. timed out vs. DNS failure.
tail_log	Last N lines of a system log, with substring filtering. Path-restricted (see below).

Every tool supports markdown (human-readable) and json (machine-readable) output.

Quickstart

Requires Python 3.10+.

git clone https://github.com/Enrique-S-J/sysops-mcp.git
cd sysops-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

The server speaks stdio and is launched by its client, so running python server.py yourself just blocks waiting for JSON-RPC on stdin. Point a client at it instead.

Claude Code

claude mcp add sysops -- /absolute/path/to/sysops-mcp/.venv/bin/python \
                         /absolute/path/to/sysops-mcp/server.py

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "sysops": {
      "command": "/absolute/path/to/sysops-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/sysops-mcp/server.py"]
    }
  }
}

Both paths must be absolute, and command must be the interpreter inside the virtualenv. A bare python3 will start but fail on import, because the system interpreter has no mcp or psutil.

Works with any MCP client that supports stdio transport.

Design notes

A few deliberate decisions, since diagnostics tooling handed to an LLM deserves some care:

• Read-only by design. No kill, no restart, no writes. An assistant can diagnose, a human decides what to do about it. Every tool is annotated readOnlyHint: true so clients can reason about safety.
• tail_log is sandboxed. Reads are restricted to allowed roots (/var/log by default) with symlinks resolved before the check, so a confused or prompt-injected client can't use it as an arbitrary file reader (/var/log/../../etc/passwd is rejected). Both sides of the containment check are resolved, because on macOS the root itself is a symlink.
• Named arguments, not a wrapper object. Each tool's parameters are individual schema properties carrying their own descriptions, rather than one nested object the model has to unpack. The descriptions are what the model reads to decide how to call a tool, so they belong on the arguments.
• Only actionable signals raise alarms. Read-only mounts can't have space reclaimed, and some are full by construction — every Ubuntu host with snaps carries squashfs mounts pinned at 100%. Counting those would report "a disk is nearly full" forever and train the reader to ignore it.
• Errors teach the next step. A failed port check tells you whether the connection was refused (host up, nothing listening) or timed out (host down or firewalled), because those imply different follow-ups. A bad disk path suggests calling the tool without arguments to list valid mounts.
• Context-efficient responses. Markdown output is trimmed for an LLM's context window: rounded numbers, human-readable timestamps, no metadata dumps. Full fidelity is available via response_format: "json".
• Interpretation included. get_host_summary doesn't just return numbers; it computes load-per-core and returns an assessment ("memory is nearly exhausted"), so the model spends its reasoning on the problem rather than the arithmetic.

Testing

pip install -e ".[dev]"
pytest

37 tests across two suites:

• test_server.py — tool output shape, sorting/filtering, port-check outcomes (open, closed, DNS failure, via a real ephemeral listener), the log path sandbox including traversal attempts, and the summary's assessment thresholds against synthetic hosts (swapping, exhausted RAM, full read-only mounts).
• test_protocol.py — the MCP layer itself: that every parameter is advertised as a named property with its own description, that required arguments and read-only annotations survive serialization, and that the log sandbox and argument bounds hold on the real call path. Direct function calls can't catch a schema that no client can call correctly.

CI runs the suite on Linux and macOS across Python 3.10–3.13. Both operating systems are deliberate: this server has shipped two bugs that were invisible on one platform and broken on the other.

Roadmap

• get_service_status (systemd unit states)
• Docker container visibility (when a socket is present)
• Streamable HTTP transport for remote hosts

License

MIT