MCP Hub

One MCP server that gives your AI assistant the keys to your whole homelab.

MCP Hub is a single Model Context Protocol server that sits on one machine in your network and fans out from there: SSH to every host in your fleet, Proxmox containers, Docker, Synology DSM, Cloudflare tunnels and DNS, n8n workflows, Notion, your password vault. Instead of running a dozen MCP servers and wiring each one into your client, you run one and point your assistant at it.

"Why is Jellyfin unreachable?" — and the assistant checks the container, reads the journal, notices the tunnel ingress is stale, fixes it, and tells you what it did.

⚠️ Read SECURITY.md before you deploy this. MCP Hub hands an LLM root shell access across your fleet. That is the point of it, and it is genuinely dangerous. Defaults are safe (127.0.0.1, read-only); the danger starts when you change them.

Troubleshooting demo

The repository includes a sanitized Asciinema recording of a complete, observation-first troubleshooting session: failed endpoint, systemd diagnosis, exact mutation plan, explicit confirmation, restart, and final health checks. It uses the example inventory and contains no private infrastructure data.

asciinema play docs/troubleshooting.cast

See the recording directly when Asciinema is not installed; the cast format is newline-delimited JSON and remains reviewable.

Related MCP server: homelab-mcp

Contents

• Features

• Quick start

• Deployment

• Local testing

• Rescue diagnostics

• Configuration

• Tool reference

• Security

• Versioning

• Contributing

Features

• 103 tools, one endpoint, one config file.

• Config-driven. Your network lives in hosts.yaml and .env. Nothing about your infrastructure is baked into the code.

• Multiplexed SSH. Persistent control sockets, so fleet-wide commands take milliseconds rather than a TCP handshake each.

• Optional integrations. Every integration is off by default and enabled with a single flag. Run it as a pure SSH fleet tool if that is all you want.

• Pluggable secrets. Read credentials from the environment, or from a Bitwarden/Vaultwarden vault via bw serve.

• Bearer-token authentication on top of an unguessable endpoint path.

• Global read-only mode, on by default: one flag disables all 39 mutating tools, enforced centrally rather than tool by tool.

• Automatic secret redaction in file reads and command output.

• Background jobs with polling, logs, and a persistent SQLite state store.

Quick start

Requires Python 3.11+ and a Linux host with SSH access to the machines you want to manage.

git clone https://github.com/wnx82/mcp-hub.git
cd mcp-hub

python3 -m venv .venv && . .venv/bin/activate
pip install -e .

cp .env.example .env                  # then edit — see below
cp hosts.example.yaml hosts.yaml      # then edit: your fleet
chmod 600 .env hosts.yaml

python server.py

At minimum, set these two in .env:

MCP_SECRET_PATH=/$(openssl rand -hex 16)   # unguessable endpoint path
MCP_AUTH_TOKEN=$(openssl rand -hex 32)     # bearer token — the real auth

The server then listens on http://127.0.0.1:8000<MCP_SECRET_PATH>, with MCP_READ_ONLY=true. Point your MCP client at that URL and send Authorization: Bearer <MCP_AUTH_TOKEN>. Requests without the token get a 401; requests to any other path get a 404.

For a systemd deployment, sudo ./deploy/install.sh creates a dedicated mcphub user and SSH key, generates both secrets into /etc/default/mcp-hub, and installs the unit. It is idempotent and never overwrites existing config. See deploy/.

For a complete Claude Code setup, safe token handling, connection checks, a first read-only prompt, and the current Claude Desktop limitation, see Connect MCP Hub to Claude.

If you want your assistant to understand your private topology, host roles, change windows, and MCP operating rules without committing any of that data, start from PROJECT_INSTRUCTIONS.example.md and keep your customized PROJECT_INSTRUCTIONS.md local-only.

Deployment

MCP Hub supports three execution modes:

The Python package and direct execution use the current checkout and its virtualenv. They do not create a service account, SSH key, environment file, or restart policy. The systemd installer provisions those operational pieces, keeps local configuration intact when rerun, and installs Rescue outside the hub virtualenv.

Container images are not an official deployment target yet. The hub needs network access, an SSH identity, persistent state.db, and access to its local inventory; operators packaging it in a container must preserve those properties themselves.

See docs/docker-packaging.md for the current requirements and what an official image would need to guarantee before it could be recommended.

Local testing

For a contributor-focused checklist covering lint, unit tests, tool registration, generated docs, installer smoke tests, and a manual read-only run, see docs/testing-local.md.

Before opening a PR or publishing a branch, you can also run the local release readiness checks:

python3 scripts/check_repo_hygiene.py
python3 scripts/check_tool_annotations.py
python3 scripts/check_security_readiness.py

To wire the security readiness check into Git automatically on push:

./scripts/install_pre_push_hook.sh

Architecture

server.py remains the FastMCP composition root while domain code is moving incrementally into tools/. SSH command construction, Cloudflare paths and response extraction, DSM protocol metadata, inventory, and playbook builders are already isolated. tools/registry.py assigns extracted tools to a domain; that domain is included in each audit summary. New protocol logic should live in its domain module and must not import server.py.

Future integrations are prioritized in docs/integration-evaluation.md, including their least-privilege scope and promotion gates.

Rescue diagnostics

mcp-hub-rescue is a read-only local CLI designed to keep working when the main server cannot import or its virtualenv is broken. The systemd installer copies it to /opt/mcp-hub-rescue and runs it with the system Python, outside the MCP Hub process and virtualenv.

sudo mcp-hub-rescue doctor
sudo mcp-hub-rescue status
sudo mcp-hub-rescue health
sudo mcp-hub-rescue logs --lines 50
sudo mcp-hub-rescue validate-config

Results are structured JSON. Rescue never imports server.py, tools/*, MCP, or an optional integration, and this boundary is enforced by CI. The current commands only observe and diagnose; restart, repair, and rollback operations will be added separately with confirmation and last-known-good safeguards.

Configuration

All git-ignored — each has a tracked .example template:

A host entry is minimal by design:

hosts:
  nas:
    hostname: nas.example.lan
    user: admin
    role: storage
    tags: [nas, backup]
    mac: "aa:bb:cc:dd:ee:01"   # optional, enables wake_host()

Tags are how you address groups: fleet_exec(tag="backup", command="df -h"). For a copy-ready two-host inventory, start with docs/examples/hosts.minimal.yaml. The larger hosts.example.yaml demonstrates every supported host option.

Pair it with docs/examples/topology.guarded.yaml to map Proxmox guests, record stale-address traps, and surface infrastructure that must not be changed casually. The _do_not_touch entries are operational context for the assistant, not an enforced access-control boundary; use token profiles and host restrictions for technical enforcement.

Add docs/examples/endpoints.minimal.yaml to monitor always-on and intermittent HTTP services. Call endpoints_health() for the regular set, or endpoints_health(include_intermittent=true) to include services that may normally be powered off. Responses from 200 through 399 count as healthy; redirects are not followed.

The complete defaults, limits, integration settings, and secret-handling notes are in the environment variable reference.

Pair those tracked examples with a private, untracked PROJECT_INSTRUCTIONS.md so your assistant sees topology caveats, maintenance windows, naming conventions, and "do not touch" guidance that should not live in the repository.

Tool reference

Every tool returns the same top-level envelope:

{
  "ok": true,
  "data": {},
  "error": null,
  "duration_ms": 12,
  "host": "example",
  "request_id": "4d52b1f69b974b7784bf65dd",
  "tool": "system_info"
}

data contains the tool-specific payload. Security refusals and controlled exceptions use the same shape with ok: false, making chained calls and audit correlation predictable.

The central tool wrapper also bounds request size, calls per token, concurrent calls per target, repeated target failures, and mutation frequency. Defaults are documented in .env.example; limit refusals use the same response envelope and audit trail as every other call.

The complete generated tool reference expands every group into a table with each tool's exact signature and model-facing description. CI verifies it against the registered functions.

Guided diagnostics always stop after observation. They return evidence, assessment, and suggested next steps with correction_applied: false; check_backup_chain is a freshness and storage signal, not proof that a restore will succeed.

Security

MCP Hub is a remote code execution service by design. Before exposing it:

• Keep the default 127.0.0.1 bind, or put it behind a tunnel with access policies.

• Set MCP_AUTH_TOKEN — the secret URL path is obscurity, not authentication.

• Leave MCP_READ_ONLY=true until you trust what your model does with it.

• Keep the resource-guard defaults enabled, then tune them from observed audit traffic rather than disabling them.

• Give it a dedicated SSH key and a minimal hosts.yaml.

Full threat model, hardening guide, and vulnerability reporting: SECURITY.md.

For a local pre-publish checklist and optional Git hook that catches common secret-leak mistakes before push, see scripts/check_security_readiness.py and scripts/install_pre_push_hook.sh.

Versioning

SemVer. Pre-1.0, breaking changes bump the minor — so read the Changed and Removed notes before upgrading one. _version.py is the single source of truth; the running server reports it via mcp-hub --version, in the MCP handshake, and in mcp_health.

Every release is documented in CHANGELOG.md, with security-relevant changes called out in their own section.

Contributing

Issues and pull requests are welcome — bug reports, new integrations, and documentation fixes especially. See CONTRIBUTING.md.

License

MIT © wnx82