Skip to main content
Glama
t-philip

homelab-mcp

by t-philip
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

homelab-mcp

A small Model Context Protocol server that gives an MCP client (Claude Desktop, Claude Code, or any other) read-only visibility into homelab infrastructure: Proxmox VE, NetBox, and systemd services over SSH, with more backends to come.

Status: v1.0.0. 8 adapters, 28 read-only tools. See docs/DESIGN_SPEC.md.

Why

Asking an assistant "is the reverse-proxy container up?" or "which VMs are using the most memory?" should be one clean tool call, not a reconstructed curl … | jq. This server turns each backing system into a handful of typed, documented, read-only tools.

Related MCP server: mcp-homelab

The read-only guarantee

Every tool only reads state. No adapter may register a tool whose name begins with a state-changing verb (restart, delete, set, …). This is enforced in three places: in the registry at startup, by a unit test over the real adapter set, and by scripts/check_no_write_tools.py in CI. If you want an assistant to act, that belongs in a separate, deliberately-scoped server — not this one.

Install

pipx install homelab-mcp          # or: uv tool install homelab-mcp

Configure

cp homelab-mcp.example.toml homelab-mcp.toml
$EDITOR homelab-mcp.toml

Secrets are never stored in the file. A field ending in _env names an environment variable; the value is read from the environment at startup.

export NETBOX_TOKEN=...           # matches token_env in the config
homelab-mcp doctor -c homelab-mcp.toml   # probe every enabled adapter

Run

homelab-mcp run -c homelab-mcp.toml

Transports — your choice

  • stdio (default) — no network port; the MCP client spawns the server as a subprocess. Register it with your client the usual way, e.g. for Claude Code:

    claude mcp add homelab -- homelab-mcp run -c /path/to/homelab-mcp.toml

  • streamable-http (and legacy sse) — for when the client runs on a different host. Set transport, host, port, http_path in the config (or pass --transport/--host/--port), and bind to a LAN or VPN address only — never a public interface. build_http_app() also returns the raw Starlette app if you'd rather host it behind your own ASGI server.

    homelab-mcp run -c homelab-mcp.toml --transport streamable-http --host 192.0.2.10 --port 9000

Adapters

Adapter

Tools

proxmox

proxmox_list_nodes, proxmox_list_guests, proxmox_guest_status, proxmox_node_resources

netbox

netbox_find_device, netbox_list_devices, netbox_device_by_ip, netbox_ip_usage

systemd

systemd_service_status, systemd_failed_units, systemd_recent_log

grafana

grafana_list_dashboards, grafana_dashboard, grafana_list_alerts, grafana_health

influxdb

influxdb_list_buckets, influxdb_measurements, influxdb_field_keys, influxdb_latest_value

adguard

adguard_status, adguard_stats, adguard_top_clients, adguard_top_domains, adguard_query_log

pinglog

pinglog_summary, pinglog_target_history

http_json

http_json_list_endpoints, http_json_get

The influxdb adapter never runs model-supplied Flux — every query is built from validated bucket / measurement / field / tag parts. The http_json adapter can only fetch endpoints named in the config, never an arbitrary URL.

Develop

uv sync
uv run pytest
uv run ruff check .
uv run mypy
uv run python scripts/check_no_write_tools.py
git config core.hooksPath .githooks    # once per clone — privacy pre-push hook

Logging goes to stderr; set the level with [server].log_level in the config or --log-level. See docs/PRIVACY.md before pushing anything public.

License

GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See LICENSE.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Overwatch MCP

    malindarathnayake
    A
    license
    Not graded
    quality
    C
    maintenance
    An MCP server that enables querying logs and metrics from Graylog, Prometheus, and InfluxDB 2.x. It provides tools for executing Lucene log searches, PromQL queries, and Flux queries directly within MCP-compatible clients.
    MIT

  • mcp-homelab

    asvarnon
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that gives AI assistants real-time access to your homelab infrastructure. It enables querying node status, managing Docker containers, controlling Proxmox VMs, and inspecting OPNsense firewall state through natural conversation.
    2
    MIT

  • runtime-inspector-mcp

    ludi-uni
    A
    license
    Not graded
    quality
    C
    maintenance
    Read-only MCP server to inspect allowlisted Docker containers, systemd services, JSONL logs, and HTTP health endpoints without arbitrary shell access.
    MIT

  • muninn-mcp

    Vanilla-Game
    A
    license
    Not graded
    quality
    F
    maintenance
    Read-only MCP server exposing one Muninn Minecraft backend's capabilities via safe, capability-aware tools. Broadly covers server status, CoreProtect lookups, Paper, CMI, and WorldGuard queries.
    MIT