HDHomeRun MCP

https://knuckles-team.github.io/hdhomerun-mcp/
Admin
HDHomeRun MCP is an API client, Model Context Protocol (MCP) server, and A2A agent for discovering,...
Tokens:7,910
Snippets:79
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### CLI setup and run example

Source: https://knuckles-team.github.io/hdhomerun-mcp/usage

Shows how to set required environment variables and run the CLI with stdio transport. HDHOMERUN_DEVICE_AUTH is only needed for DVR cloud calls.

```bash
export HDHOMERUN_URL="http://10.0.132.114"
export HDHOMERUN_DEVICE_AUTH="your_device_auth"   # only needed for DVR cloud calls
hdhomerun-mcp --transport stdio

```

--------------------------------

### Install hdhomerun-mcp from source

Source: https://knuckles-team.github.io/hdhomerun-mcp/installation

Clone the repository and install in editable mode with all extras.

```bash
git clone https://github.com/Knuckles-Team/hdhomerun-mcp.git
cd hdhomerun-mcp
pip install -e ".[all]"
```

--------------------------------

### Install hdhomerun-mcp with all extras

Source: https://knuckles-team.github.io/hdhomerun-mcp/installation?q=

Installs the package with the all extra, which pulls in everything above (mcp and agent extras).

```bash
pip install "hdhomerun-mcp[all]"
```

--------------------------------

### Install hdhomerun-mcp from PyPI

Source: https://knuckles-team.github.io/hdhomerun-mcp/installation

Install the hdhomerun-mcp package from PyPI. Requires Python 3.11-3.14 and a reachable HDHomeRun tuner on the local network.

```bash
pip install hdhomerun-mcp
```

--------------------------------

### Install hdhomerun-mcp with agent extra

Source: https://knuckles-team.github.io/hdhomerun-mcp/installation?q=

Installs the package with the agent extra, which pulls in the Pydantic-AI agent and Logfire tracing.

```bash
pip install "hdhomerun-mcp[agent]"
```

--------------------------------

### Install hdhomerun-mcp optional extras

Source: https://knuckles-team.github.io/hdhomerun-mcp/installation

Install optional extras: mcp for the FastMCP MCP-server runtime, agent for Pydantic-AI agent and Logfire tracing, and all for everything.

```bash
pip install "hdhomerun-mcp[mcp]"
```

```bash
pip install "hdhomerun-mcp[agent]"
```

```bash
pip install "hdhomerun-mcp[all]"
```

--------------------------------

### Python API usage example

Source: https://knuckles-team.github.io/hdhomerun-mcp/usage

Shows how to import the client and use various methods for HTTP JSON API, discovery, tuner status, DVR rules, and doctor. Requires HDHOMERUN_URL, HDHOMERUN_DEVICE_AUTH, and HDHOMERUN_SSL_VERIFY environment variables.

```python
from hdhomerun_mcp.auth import get_client

client = get_client()  # reads HDHOMERUN_URL / HDHOMERUN_DEVICE_AUTH / HDHOMERUN_SSL_VERIFY

# HTTP JSON API
info = client.get_discover()
lineup = client.get_lineup()
status = client.get_lineup_status()
client.start_scan(source="Antenna")
url = client.build_stream_url("24.1", tuner=0, duration=30)

# Discovery
devices = client.discover_local_broadcast(timeout=2.0)     # may be empty across VLANs
devices = client.discover_cloud(device_id="10ACFCDE")       # cloud fallback

# hdhomerun_config binary control protocol (TCP :65001)
tuner_status = client.get_tuner_status(0)
parsed = client.parse_tuner_status(tuner_status)

# DVR (cloud recording rules)
rules = client.list_recording_rules()

# Doctor
report = client.run_doctor(signal_channels=["24.1"])

```

--------------------------------

### Install hdhomerun-mcp with mcp extra

Source: https://knuckles-team.github.io/hdhomerun-mcp/installation?q=

Installs the package with the mcp extra, which pulls in the FastMCP MCP-server runtime (agent-utilities[mcp]).

```bash
pip install "hdhomerun-mcp[mcp]"
```

--------------------------------

### Streamable-HTTP local process launch and URL config

Source: https://knuckles-team.github.io/hdhomerun-mcp/deployment

Start a local streamable-http server on port 8000 and verify it with the health endpoint, then connect to it by URL in mcp_config.json.

```bash
uvx --from "hdhomerun-mcp[mcp]" hdhomerun-mcp --transport streamable-http --host 0.0.0.0 --port 8000
curl -s http://localhost:8000/health        # {"status":"OK"}

```

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

```

--------------------------------

### Local container / uv - streamable-http compose and connect

Source: https://knuckles-team.github.io/hdhomerun-mcp/deployment?q=

Commands to start a local streamable-http container via docker compose and then connect to it by URL using mcp_config.json.

```bash
docker compose -f docker/mcp.compose.yml up -d
```

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

--------------------------------

### Docker Compose commands

Source: https://knuckles-team.github.io/hdhomerun-mcp/deployment?q=

Commands to start the MCP server only or both MCP and agent using the provided compose files.

```bash
docker compose -f docker/mcp.compose.yml up -d      # MCP server only
docker compose -f docker/agent.compose.yml up -d    # MCP + agent
```

--------------------------------

### Streamable-HTTP (local process) launch and health check

Source: https://knuckles-team.github.io/hdhomerun-mcp/deployment?q=

Command to start the MCP server with streamable-http transport on localhost:8000, followed by a curl health check that returns {"status":"OK"}.

```bash
uvx --from "hdhomerun-mcp[mcp]" hdhomerun-mcp --transport streamable-http --host 0.0.0.0 --port 8000
curl -s http://localhost:8000/health        # {"status":"OK"}
```

--------------------------------

### CLI: export env vars and run hdhomerun-mcp

Source: https://knuckles-team.github.io/hdhomerun-mcp/usage?q=

Run the CLI with stdio transport. Set HDHOMERUN_URL and optionally HDHOMERUN_DEVICE_AUTH (only needed for DVR cloud calls).

```bash
export HDHOMERUN_URL="http://10.0.132.114"
export HDHOMERUN_DEVICE_AUTH="your_device_auth"   # only needed for DVR cloud calls
hdhomerun-mcp --transport stdio
```

--------------------------------

### Local container / uv - Docker stdio mcp_config.json

Source: https://knuckles-team.github.io/hdhomerun-mcp/deployment?q=

Configuration to launch a Docker container directly from mcp_config.json using the 'command' key. Swap 'docker' for 'podman' for a daemonless runtime.

```json
{
  "mcpServers": {
    "hdhomerun-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "TRANSPORT=stdio",
        "-e", "HDHOMERUN_URL=https://service.example.com",
        "-e", "HDHOMERUN_DEVICE_AUTH=your_token",
        "knucklessg1/hdhomerun-mcp:1.1.0"
      ]
    }
  }
}
```

--------------------------------

### stdio (local subprocess) mcp_config.json

Source: https://knuckles-team.github.io/hdhomerun-mcp/deployment?q=

Configuration for launching hdhomerun-mcp as a local subprocess via stdio. Uses the 'command' key with uvx and sets HDHOMERUN_URL and HDHOMERUN_DEVICE_AUTH environment variables.

```json
{
  "mcpServers": {
    "hdhomerun-mcp": {
      "command": "uvx",
      "args": ["--from", "hdhomerun-mcp[mcp]", "hdhomerun-mcp"],
      "env": {
        "HDHOMERUN_URL": "https://service.example.com",
        "HDHOMERUN_DEVICE_AUTH": "your_token"
      }
    }
  }
}
```

--------------------------------

### Connect to streamable-http process by URL

Source: https://knuckles-team.github.io/hdhomerun-mcp/deployment?q=

mcp_config.json to connect to a locally running streamable-http server via the 'url' key.

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

--------------------------------

### Local container via docker mcp_config.json

Source: https://knuckles-team.github.io/hdhomerun-mcp/deployment

Launch a container directly from mcp_config.json using the docker command. Swap docker for podman for a daemonless runtime.

```json
{
  "mcpServers": {
    "hdhomerun-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "TRANSPORT=stdio",
        "-e", "HDHOMERUN_URL=https://service.example.com",
        "-e", "HDHOMERUN_DEVICE_AUTH=your_token",
        "knucklessg1/hdhomerun-mcp:1.1.0"
      ]
    }
  }
}

```

--------------------------------

### Python API: get_client() and common operations

Source: https://knuckles-team.github.io/hdhomerun-mcp/usage?q=

Use this Python API to access the same capabilities as the MCP tools and CLI. The client reads HDHOMERUN_URL, HDHOMERUN_DEVICE_AUTH, and HDHOMERUN_SSL_VERIFY from the environment. Note that discover_local_broadcast may return empty across VLANs, and discover_cloud is a fallback.

```python
from hdhomerun_mcp.auth import get_client

client = get_client()  # reads HDHOMERUN_URL / HDHOMERUN_DEVICE_AUTH / HDHOMERUN_SSL_VERIFY

# HTTP JSON API
info = client.get_discover()
lineup = client.get_lineup()
status = client.get_lineup_status()
client.start_scan(source="Antenna")
url = client.build_stream_url("24.1", tuner=0, duration=30)

# Discovery
devices = client.discover_local_broadcast(timeout=2.0)     # may be empty across VLANs
devices = client.discover_cloud(device_id="10ACFCDE")       # cloud fallback

# hdhomerun_config binary control protocol (TCP :65001)
tuner_status = client.get_tuner_status(0)
parsed = client.parse_tuner_status(tuner_status)

# DVR (cloud recording rules)
rules = client.list_recording_rules()

# Doctor
report = client.run_doctor(signal_channels=["24.1"])
```

--------------------------------

### Pull hdhomerun-mcp Docker image

Source: https://knuckles-team.github.io/hdhomerun-mcp/installation

Pull the prebuilt container image version 1.1.0 from Docker Hub.

```bash
docker pull knucklessg1/hdhomerun-mcp:1.1.0
```

--------------------------------

### Run the A2A agent server

Source: https://knuckles-team.github.io/hdhomerun-mcp/deployment?q=

Command to run the A2A agent server with a specified MCP config and web interface.

```bash
hdhomerun-agent --mcp-config mcp_config.json --web
```

--------------------------------

### Remote URL (deployed behind Caddy) mcp_config.json

Source: https://knuckles-team.github.io/hdhomerun-mcp/deployment?q=

Configuration to connect to a remotely deployed hdhomerun-mcp server via the 'url' key. No local process or image required.

```json
{
  "mcpServers": {
    "hdhomerun-mcp": { "url": "https://hdhomerun-mcp.example.invalid/mcp" }
  }
}
```
Tokens:
Raw