HDHomeRun MCP

HDHomeRun MCP

CLI or API | MCP | Agent

Version: 0.1.0

Documentation — Installation, deployment, usage across the API, CLI, and MCPinterfaces, the integrated A2A agent server, and guidance for provisioning thebacking platform are maintained in theofficial documentation.

Table of Contents

• Overview
• Key Features
• Available MCP Tools
• Installation
• Usage
• MCP
• Documentation

Overview

HDHomeRun MCP MCP Server + A2A Agent

A complete client + MCP server + A2A agent for SiliconDust HDHomeRun network TVtuners, covering all four of SiliconDust's documented interfaces: the HTTP JSONAPI (device discovery, channel lineup, scan control), the DVR API(SiliconDust cloud recording rules + local record-engine operations), theDiscovery API (local UDP broadcast on port 65001 + the cloud discoveryendpoint), and the binary hdhomerun_config control protocol (TCP port65001 — a different wire protocol from the HTTP API, used for per-tunerstatus/vstatus/streaminfo/tuning/filters). Also ships a doctor diagnostictool matching this fleet's cm_doctor convention.

This repository is actively maintained - Contributions are welcome!

Key Features

• All four HDHomeRun interfaces, one package — HTTP JSON API, DVR API,Discovery API (local UDP + cloud), and the binary hdhomerun_config controlprotocol, each its own action-routed tool domain.
• doctor diagnostics — one call checks device reachability, firmware/model,tuner count vs. a paired Jellyfin instance, per-channel signal strength,DeviceAuth presence/validity, and discovery-cache freshness — pass/fail with anactionable next step per check.
• Action-routed MCP tools — each domain is exposed as a single MCP tool that routesto many underlying operations via an action argument, keeping the tool surface small.
• Three interfaces, one package — use it as a Python API client, an MCP server(stdio / streamable-http / sse), or a Pydantic-AI A2A agent.
• agent-utilities native — built on the shared framework (auth, action router,telemetry, governance) for fleet consistency.
• Per-tool toggles — enable or disable each tool domain with environment switches.
• Enterprise-ready — OTEL/Langfuse telemetry and optional Eunomia access governance.

Available MCP Tools

Each tool is action-routed: pass an action and a JSON params_json payload. Tooldomains can be toggled on or off with the listed environment variable. The table below isauto-generated from the live server by the mcp-readme-table pre-commit hook(python -m agent_utilities.mcp.readme_tools) — do not edit it by hand.

Condensed action-routed tools (MCP_TOOL_MODE=condensed)

Verbose 1:1 API-mapped tools (MCP_TOOL_MODE=verbose or both)

5 action-routed tool(s) · 57 verbose 1:1 tool(s). Each is enabled unless its <DOMAIN>TOOL toggle is set false; MCP_TOOL_MODE selects the surface (intent default — the six verb-tools, granular set loaded on demand · condensed action-routed · verbose 1:1 · both). Auto-generated — do not edit.

Installation

Install with uvx (no install — run on demand)

uvx --from "hdhomerun-mcp[mcp]" hdhomerun-mcp      # MCP server (slim deps)
uvx --from "hdhomerun-mcp[agent]" hdhomerun-agent  # A2A agent server (full runtime)

The [mcp] extra installs only the FastMCP/FastAPI MCP-server tooling(agent-utilities[mcp]) — it excludes the heavy agent runtime (theepistemic-graph engine, pydantic-ai, dspy, llama-index), so it is farsmaller. Use [agent] only when you run the integrated agent.

Install with pip

python -m pip install hdhomerun-mcp            # core (API client)
python -m pip install "hdhomerun-mcp[all]"     # + MCP server + A2A agent + telemetry

Console scripts

After installation the following entry points are available on your PATH:

Usage

As a Python API client

from hdhomerun_mcp.auth import get_client

client = get_client()  # reads HDHOMERUN_URL / HDHOMERUN_DEVICE_AUTH
info = client.get_discover()          # device identity + tuner count
lineup = client.get_lineup()          # channel list
stream_url = client.build_stream_url("24.1")  # http://<device>:5004/auto/v24.1
report = client.run_doctor()          # full health-check sweep

As an MCP server (CLI)

# Local stdio (for IDEs)
hdhomerun-mcp

# Networked streamable-http
hdhomerun-mcp --transport streamable-http --host 0.0.0.0 --port 8000

Calling an MCP tool

Tools are action-routed — pass an action plus a JSON params_json string:

{
  "tool": "http_operations",
  "arguments": {
    "action": "discover",
    "params_json": "{}"
  }
}

MCP

Using as an MCP Server

The MCP Server can be run in stdio (local), streamable-http (networked), orsse mode.

Environment Variables

Package environment variables

Inherited agent-utilities variables (apply to every connector)

20 package + 15 inherited variable(s). Auto-generated from .env.example + the shared agent-utilities set — do not edit.

• HDHOMERUN_URL: The HDHomeRun device base URL (e.g. http://10.0.132.114 or http://hdhomerun.arpa).
• HDHOMERUN_DEVICE_AUTH: The device's DeviceAuth token (only needed for SiliconDust cloud DVR calls; rotates on reboot/firmware update — do not hardcode).

MCP Configuration Examples

Install the slim [mcp] extra. All examples install hdhomerun-mcp[mcp] — theMCP-server extra that pulls only the FastMCP / FastAPI tooling (agent-utilities[mcp]).It deliberately excludes the heavy agent runtime (pydantic-ai, the epistemic-graphengine, dspy, llama-index), so uvx / container installs are far smaller. Use thefull [agent] extra only when you need the integrated Pydantic AI agent.

stdio Transport (local IDEs — Cursor, Claude Desktop, VS Code)

{
  "mcpServers": {
    "hdhomerun-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "hdhomerun-mcp[mcp]",
        "hdhomerun-mcp"
      ],
      "env": {
        "MCP_TOOL_MODE": "intent",
        "CONFIGTOOL": "True",
        "DISCOVERYTOOL": "True",
        "DOCTORTOOL": "True",
        "DVRTOOL": "True",
        "HDHOMERUN_DEVICE_AUTH": "your_device_auth_here",
        "HDHOMERUN_URL": "http://hdhomerun.local",
        "HTTPTOOL": "True"
      }
    }
  }
}

Streamable-HTTP Transport (networked / production)

{
  "mcpServers": {
    "hdhomerun-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "hdhomerun-mcp[mcp]",
        "hdhomerun-mcp",
        "--transport",
        "streamable-http",
        "--port",
        "8000"
      ],
      "env": {
        "TRANSPORT": "streamable-http",
        "HOST": "0.0.0.0",
        "PORT": "8000",
        "MCP_TOOL_MODE": "intent",
        "CONFIGTOOL": "True",
        "DISCOVERYTOOL": "True",
        "DOCTORTOOL": "True",
        "DVRTOOL": "True",
        "HDHOMERUN_DEVICE_AUTH": "your_device_auth_here",
        "HDHOMERUN_URL": "http://hdhomerun.local",
        "HTTPTOOL": "True"
      }
    }
  }
}

Alternatively, connect to a pre-deployed Streamable-HTTP instance by url:

{
  "mcpServers": {
    "hdhomerun-mcp": {
      "url": "http://localhost:8000/hdhomerun-mcp/mcp"
    }
  }
}

Deploying the Streamable-HTTP server via Docker:

docker run -d \
  --name hdhomerun-mcp-mcp \
  -p 8000:8000 \
  -e TRANSPORT=streamable-http \
  -e HOST=0.0.0.0 \
  -e PORT=8000 \
  -e MCP_TOOL_MODE=intent \
  -e CONFIGTOOL=True \
  -e DISCOVERYTOOL=True \
  -e DOCTORTOOL=True \
  -e DVRTOOL=True \
  -e HDHOMERUN_DEVICE_AUTH=your_device_auth_here \
  -e HDHOMERUN_URL=http://hdhomerun.local \
  -e HTTPTOOL=True \
  knucklessg1/hdhomerun-mcp:mcp

Auto-generated from the code-read env surface (MCP_TOOL_MODE + package vars) — do not edit.

Additional Deployment Options

hdhomerun-mcp can also run as a local container (Docker / Podman / uv) or beconsumed from a remote deployment. TheDeployment guide has full,copy-paste mcp_config.json for all four transports — stdio, streamable-http,local container / uv, and remote URL:

• Local container / uv — launch the server from mcp_config.json via uvx,docker run, or podman run, or point at a local streamable-http container by url.
• Remote URL — connect to a server deployed behind Caddy athttp://hdhomerun-mcp.arpa/mcp using the "url" key.

Container images (:mcp vs :agent)

One multi-stage docker/Dockerfile builds two right-sized images, selected by --target:

docker build --target mcp   -t knucklessg1/hdhomerun-mcp:mcp    docker/   # slim MCP server
docker build --target agent -t knucklessg1/hdhomerun-mcp:latest docker/   # full agent

Knowledge-graph database (epistemic-graph)

The full agent ([agent] / :latest) embeds the epistemic-graph engine (pulled in viaagent-utilities[agent]). For production — or to share one knowledge graph across multipleagents — run epistemic-graph as its own database container and point the agent at it.Deployment recipes (single-node + Raft HA), connection config, and the full databasearchitecture (with diagrams) are in theepistemic-graph deployment guide.The slim [mcp] server does not require the database.

Documentation

Full documentation is published to the GitHub Pages site and mirrored under docs/:

• Documentation site
• Overview
• Installation
• Usage
• Deployment
• Platform
• Concept Registry