mcp-it-ops
Provides tools for querying Docker container status, including name, image, state, health, uptime, and port mappings from a local Docker daemon.
Allows querying Grafana alert states via the Prometheus-style rules API, returning alerts grouped by state with details like name, folder, health, last evaluation, and annotations.
Enables executing Flux queries against a local InfluxDB v2 instance, returning parsed CSV records up to 500 rows (requires InfluxDB token and org environment variables).
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., "@mcp-it-ops show me all running containers"
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.
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 |
| Local host's hostname, uptime, 1-min load, memory %, root-disk %, and running container count. Reads |
| 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. |
| Profit, win rate, open trade count, balance from a freqtrade REST API. Bot name resolved via config. |
| Full |
| Loki LogQL |
| NVMe/SATA SMART health via |
| Reads |
| Executes a Flux query against the local InfluxDB v2 and returns parsed CSV records (capped at 500 rows). Auth via |
Related MCP server: log-analyzer-mcp
Roadmap
get_uptime_kuma_status— pull monitor states via Uptime Kuma APIHTTP 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 admin password (referenced from |
| freqtrade bot1 API basic auth |
| 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.pyRequirements
Python 3.10+
mcp>=1.27.0,httpx>=0.27,pyyaml>=6.0(auto-installed)Read access to
/proc,df,docker psforget_system_healthNetwork reach + credentials for the services you want tools for
How development works
src/mcp_it_ops/server.py— all tool definitionstests/— pytest tests; one file per tool (TODO: backfill)config/settings.example.yaml— committed template;config/settings.yamlis gitignored
When adding a tool: see CLAUDE.md for the workflow + design conventions.
License
MIT
Available Tools
8 toolsget_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
Scored across 8 tools
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.
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.
8 tools is an ideal size for an IT operations server. It covers all essential monitoring domains without being overwhelming or sparse.
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
Related MCP Connectors
Manage uptime monitors and incidents and search logs, metrics and traces from an AI assistant.
Uptime, SSL, DNS and domain monitoring you can talk to from Claude or any MCP client.
Monitoring + status pages set up by talking to Claude. Auto-detects 30+ SDKs and your URLs.
Manage your hosted Hermes Agent from the AI you already use: status, model, health and logs.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables 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.137-
- FlicenseBqualityDmaintenanceEnables 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-
- AlicenseAqualityDmaintenanceEnables Claude to monitor CPU, memory, disk, processes, network connections, Docker containers, and system logs for system diagnostics and troubleshooting.5MIT
- FlicenseNot gradedqualityCmaintenanceLets an LLM client monitor devices, services, disk usage, and uptime in a home network and home lab.-