Skip to main content
Glama
mcp-it-ops

mcp-it-ops

by bastiaan365

mcp-it-ops

MCP server that exposes homelab and IT-ops tools to Claude. Designed to grow tool-by-tool, starting with what's actually testable on a Linux homelab and extending toward AD / Intune / M365 when a corporate test environment is available.

Status: v0.0.5 (2026-04-19) — 8 working tools, 37 pytest tests, CI green on Python 3.10/3.11/3.12. Tools split into category modules under tools/. Locally tested on niborserver. Not yet on PyPI; install from source.

What it does today

Once installed and connected to Claude (Desktop or Code), Claude can call:

Tool

What it does

get_system_health

Local host's hostname, uptime, 1-min load, memory %, root-disk %, and running container count. Reads /proc + shells out to df and docker ps.

get_grafana_alert_state

Queries the Grafana Prometheus-style rules API and returns alerts grouped by state (firing / pending / inactive / no_data / error) with name, folder, health, last evaluation, annotations.

get_freqtrade_bot_status(bot)

Profit, win rate, open trade count, balance from a freqtrade REST API. Bot name resolved via config.

get_container_status

Full docker ps parsed into structured per-container records (name, image, state, health, uptime, ports).

query_loki_logs(query, since, limit)

Loki LogQL query_range against localhost:3100. Returns structured streams + lines, limit clamped to 1000.

get_smartd_health(device='/dev/nvme0n1')

NVMe/SATA SMART health via sudo smartctl -a — overall health, critical warning, temperature, available spare, percentage used, power-on hours, unsafe shutdowns, media errors.

get_backup_status

Reads /var/log/niborserver-backup.log and reports last_run_started/completed/duration/size/succeeded. Closes the "watch the watchers" loop.

query_influxdb_flux(flux, bucket)

Executes a Flux query against the local InfluxDB v2 and returns parsed CSV records (capped at 500 rows). Auth via INFLUXDB_TOKEN + INFLUXDB_ORG env vars.

Related MCP server: log-analyzer-mcp

Roadmap

  • get_uptime_kuma_status — pull monitor states via Uptime Kuma API

  • HTTP transport so openclaw / other tailnet peers can query niborserver-resident tools (currently stdio only)

  • Eventually: get_ad_user, get_intune_compliance, get_m365_service_health — when a corporate test environment is available

Quickstart

On the host where the MCP server will run

git clone https://github.com/bastiaan365/mcp-it-ops.git
cd mcp-it-ops
python3 -m venv .venv
.venv/bin/pip install -e .

Configuration

Copy the example and customise:

cp config/settings.example.yaml config/settings.yaml
# Edit config/settings.yaml — point at your Grafana, freqtrade bots, etc.

Secrets come from environment variables, never from the YAML. Default env var names:

Env var

What

GRAFANA_PASSWORD

Grafana admin password (referenced from grafana.password_env)

FT_STEADY_USER / FT_STEADY_PASS

freqtrade bot1 API basic auth

FT_FUN_USER / FT_FUN_PASS

freqtrade bot2 API basic auth

Connect to Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%/Claude/claude_desktop_config.json on Windows:

{
  "mcpServers": {
    "it-ops": {
      "command": "/path/to/mcp-it-ops/.venv/bin/mcp-it-ops",
      "env": {
        "GRAFANA_PASSWORD": "your-grafana-password",
        "MCP_IT_OPS_CONFIG": "/path/to/mcp-it-ops/config/settings.yaml"
      }
    }
  }
}

Restart Claude Desktop. The tools appear under "it-ops".

Smoke-test without Claude

GRAFANA_PASSWORD=... .venv/bin/python -c "
from mcp_it_ops.server import get_system_health, get_grafana_alert_state
import json
print(json.dumps(get_system_health(), indent=2))
print(json.dumps(get_grafana_alert_state().get('summary'), indent=2))
"

Or use the official MCP inspector:

.venv/bin/python -m mcp dev src/mcp_it_ops/server.py

Requirements

  • Python 3.10+

  • mcp>=1.27.0, httpx>=0.27, pyyaml>=6.0 (auto-installed)

  • Read access to /proc, df, docker ps for get_system_health

  • Network reach + credentials for the services you want tools for

How development works

  • src/mcp_it_ops/server.py — all tool definitions

  • tests/ — pytest tests; one file per tool (TODO: backfill)

  • config/settings.example.yaml — committed template; config/settings.yaml is gitignored

When adding a tool: see CLAUDE.md for the workflow + design conventions.

License

MIT

Available Tools

8 tools
get_backup_statusA

Report on the niborserver backup pipeline's last run.

Reads /var/log/niborserver-backup.log and reports: last_run_started, last_run_completed, last_run_duration_seconds, last_run_size, last_run_succeeded.

Returns {"error": ...} if the log doesn't exist (backup not yet run).

Inputs: no named parameters. Returns: object

get_container_statusA

Return structured docker-ps output: per-container name, image, state, status, ports, age.

Shells out to docker ps with a tab-separated format string. Returns a list of containers plus a summary dict. Read-only — does not stop/restart anything.

Returns {"error": "..."} if docker isn't installed or the docker socket is unreachable.

Inputs: no named parameters. Returns: object

get_freqtrade_bot_statusA

Query a freqtrade bot's REST API for its current trading state.

bot_name must match a key under freqtrade.bots in config (e.g. 'steady', 'fun'). Reads basic-auth credentials from the env vars named in user_env / pass_env on the bot's config entry.

Returns a dict with: bot_name, dry_run, strategy, timeframe, exchange, closed_trade_count, open_trade_count, realised_p_and_l_fiat, realised_p_and_l_pct, total_p_and_l_fiat, total_p_and_l_pct, win_rate, open_positions (list of {pair, opened, current_pnl_fiat, current_pnl_pct}).

Returns {"error": "..."} on any failure (unknown bot, missing creds, API down).

Inputs: bot_name (required). Returns: object

get_grafana_alert_stateA

List Grafana alert rules with their current state.

Queries the Grafana Prometheus-style rules API. Reads credentials from the config (Grafana URL + user) and from the env var named in grafana.password_env (defaults to GRAFANA_PASSWORD). Returns a dict with alerts grouped by state (firing/pending/inactive/no_data/error).

Inputs: no named parameters. Returns: object

get_smartd_healthA

Query SMART health for a storage device via smartctl.

device: /dev/nvme0n1, /dev/sda, etc. Default is niborserver's NVMe. Returns: overall_health, critical_warning, temperature_c, available_spare_pct, percentage_used_pct, power_on_hours, unsafe_shutdowns, media_errors.

Requires sudo (smartctl needs raw device access). Returns {"error": ...} if smartctl isn't installed or sudo isn't permitted (the calling user must have NOPASSWD sudo for smartctl OR the MCP server must run as root).

Inputs: device. Returns: object

get_system_healthA

Report local system health: disk, memory, load, uptime, container count.

Reads from /proc and shells out to df, uptime, docker ps. Designed for the host the MCP server runs on.

Inputs: no named parameters. Returns: object

query_influxdb_fluxA

Execute a Flux query against the local InfluxDB and return parsed records.

flux: Flux query string. The bucket is NOT auto-substituted — include from(bucket:"<bucket>") |> range(start: -1h) |> ... yourself. bucket: name surfaced in the response for context (does not modify the query).

Reads InfluxDB URL from config (influxdb.url, default localhost:8086) and the org + token from the env vars named in influxdb.org_env / influxdb.token_env (default INFLUXDB_ORG / INFLUXDB_TOKEN).

Returns: {bucket, row_count, columns, records (list of dicts), truncated_at}. Records are capped at 500 rows to keep Claude's context manageable; if more were returned, truncated_at: 500 appears in the response.

Returns {"error": "..."} on missing token, network failure, or Flux syntax error.

Inputs: flux (required), bucket. Returns: object

query_loki_logsA

Search container/syslog logs via Loki LogQL.

query: LogQL query string, e.g. '{container="grafana"}' or '{container=~".+"} |= "ERROR"' since: how far back, e.g. '1h', '30m', '7d' (Loki duration syntax) limit: max log lines to return (Loki default = 100, hard-capped here at 1000)

Returns a dict with: total_streams, total_lines, streams (list of {labels, lines}). Lines are timestamp-sorted oldest-first. Returns {"error": "..."} on Loki unreachable or invalid query.

Inputs: query (required), limit, since. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a clearly distinct subsystem (backup, docker, freqtrade, grafana, smartd, system, influxdb, loki). No two tools overlap in purpose; descriptions are detailed and unambiguous.

    Naming Consistency5/5

    All tools follow a consistent verb_noun lowercase snake_case pattern. 'get_' is used for status/health retrieval and 'query_' for log/database queries, which is a sensible and predictable distinction.

    Tool Count5/5

    8 tools is an ideal size for an IT operations server. It covers all essential monitoring domains without being overwhelming or sparse.

    Completeness4/5

    The tool surface covers key IT ops areas (health, docker, backups, alerts, logs) well. Minor gaps exist (e.g., network status, CPU temperature) but do not hinder common workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      Enables Claude to monitor and manage homelab infrastructure including Docker containers, OPNsense firewall, and TrueNAS storage with configurable capability levels from read-only monitoring to full management control.
      13
      7
      -
    • F
      license
      B
      quality
      D
      maintenance
      Enables log analysis, searching, counting, and system metrics retrieval (CPU, memory, disk) via natural language, using 5 tools that can be integrated with Claude Code.
      5
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enables Claude to monitor CPU, memory, disk, processes, network connections, Docker containers, and system logs for system diagnostics and troubleshooting.
      5
      MIT