Tvheadend MCP

English · Deutsch

An MCP server for Tvheadend DVR, EPG and API-exposed DVB configuration. Its 53 tools let an MCP client inspect and configure tuners, networks, muxes, services and channels, including satellite reception with DiSEqC and Unicable/JESS.

The server reads the running Tvheadend instance's classes, field metadata and options instead of maintaining a fixed list of supported tuner models. It uses the official MCP Python SDK 2.x and supports stdio and loopback Streamable HTTP. No AI service or API key is required by this server.

Features

“API-exposed” is an important boundary: drivers, firmware, physical wiring and operating-system networking are outside this server. Some builds omit classes or endpoints. Development targets Tvheadend 4.3; older versions depend on the API they provide. Missing endpoints produce errors rather than simulated success.

Quick start

Install uv and use Python 3.11 or newer. Clone the repository for a reproducible setup:

git clone https://github.com/NemoN/tvheadend-mcp.git
cd tvheadend-mcp
git checkout v0.2.0
uv sync --frozen
cp .env.example .env

Edit .env locally with the URL and credentials of your own Tvheadend instance. The example enables TVH_READ_ONLY=true for initial exploration. Change it to false when you want tools to apply changes. The code default, if this variable is omitted, is false.

TVH_URL=http://tvheadend.example:9981
TVH_USER=mcp
TVH_PASS=replace-locally
TVH_AUTH=digest
TVH_VERIFY_SSL=true
TVH_TIMEOUT=30
TVH_TIMEZONE=Europe/Berlin
TVH_READ_ONLY=true

The Tvheadend account needs web-interface access and administrator privileges for DVB administration, plus the appropriate video-recorder permissions for DVR work. Tvheadend continues to enforce these permissions. See configuration.

Check connectivity without changing the configuration:

uv run tvheadend-mcp --check

Exit code 0 means all three status endpoints answered successfully; 1 indicates an API, connection or permission error. Starting without --check runs an MCP server and waits for a client.

Connect an MCP client

For clients using the common mcpServers JSON format, replace both absolute paths:

{
  "mcpServers": {
    "tvheadend": {
      "command": "uv",
      "args": [
        "run", "--directory", "/absolute/path/tvheadend-mcp",
        "--frozen", "tvheadend-mcp",
        "--env-file", "/absolute/path/tvheadend.env"
      ]
    }
  }
}

The env file can be the checkout's .env or another private file. If a desktop client cannot find uv, use its full executable path. Clients with a different configuration format use the same command and arguments in their MCP settings. See examples.

Alternatively, install directly from the versioned Git source without a checkout:

uvx --from git+https://github.com/NemoN/[email protected] \
  tvheadend-mcp --env-file /absolute/path/tvheadend.env

This installation uses Git source; a PyPI package or container-registry image is not required. For a fully locked environment, use the checkout and uv sync --frozen.

Streamable HTTP

uv run tvheadend-mcp --transport streamable-http --port 8000

Connect to http://127.0.0.1:8000/mcp. The HTTP listener accepts only loopback addresses and has no built-in authentication. For a remote host, use an SSH tunnel; see configuration.

Example requests

Inspect my DVB-C and DVB-S/S2 hardware and networks. Show missing assignments and use the actual tuner schemas and options before changing anything.

Find free-to-air TV services, show the proposed channel list and map the services I choose. Prefer HD services and preserve existing channel numbers.

Find the next showing of a programme in my EPG and schedule a recording using my default recording profile.

Follow the DVB setup guide for tuners, Unicable, SAT>IP, networks, scans, channel mapping and EPG. The same basic workflow is available to MCP clients as the resource tvheadend://workflow.

New in 0.2.0

See the EPG, reception and maintenance guide for complete workflows and recovery limits. The new tools can measure EPG time coverage and description presence, manage native grabbers, test received media packets, and prepare channel/network cleanup plans that preserve retained channel UUIDs.

A tuner-specific probe temporarily isolates the selected frontend, requires an idle server and no imminent DVR, and records a recovery journal before changing settings. Probes and maintenance execution preview by default.

Tool reference

All tools start with tvh_. The complete reference documents their arguments and descriptions.

List calls default to 100 entries, EPG searches to 50; the maximum is 1000 per request. Advance start until total is reached. assign_networks and assign_services default to adding entries; a general update_node replaces each supplied array in full.

create_mux.frequency_hz uses Hz and converts DVB-S/S2 to Tvheadend's native kHz. Native settings.frequency is also supported, but cannot be supplied together with frequency_hz. Symbol rates use symbols per second.

Changes and recovery

Write tools accept dry_run=true to preview their endpoint and parameters. Normally they execute immediately; restore_snapshot, probe_reception and apply_maintenance_plan preview by default. Maintenance planning never writes to Tvheadend; applying a plan requires its unexpired ID from the same process. TVH_READ_ONLY=true blocks writes while allowing reads and previews.

Snapshots contain selected writable settings, excluding password, read-only and write-once fields. They are not complete backups and cannot recreate deleted objects, restore media or recover old hardware child UUIDs. Restoration is non-atomic and reports partial results. Back up the complete Tvheadend configuration directory before structural changes.

Deleting a network can also delete its muxes and services. DVR stop, cancel and remove_files have different meanings: remove_files permanently deletes recording files. Consult the security and trust model.

Docker

docker build -t tvheadend-mcp .
docker run --rm -i --env-file .env tvheadend-mcp

Use -i without -t for stdio. TVH_URL must resolve and be reachable from the container; localhost inside the container refers to that container. The image runs as an unprivileged user and installs hashed runtime dependencies from requirements.lock. No prebuilt container image is currently published. For tuner-isolation probes, mount a persistent state folder writable by UID 65534 and set TVH_STATE_DIR to that folder inside the container (for example /state).

Development

uv sync --frozen
uv run pytest -q
uv run ruff check src tests scripts
uv run ruff format --check src tests scripts
uv build
uv run python scripts/check_artifacts.py dist/*

Tests use mocked Tvheadend HTTP responses and a real MCP stdio subprocess; they do not require access to a live tuner. CI runs them on Python 3.11–3.14, checks formatting and package contents, and builds the Docker image. See CONTRIBUTING.md and CHANGELOG.md.

Project information

MIT licensed. Independent project; not affiliated with Tvheadend or a tuner manufacturer. Report reproducible problems through GitHub Issues without credentials or configuration backups. Please use the private reporting route described in SECURITY.md for vulnerabilities.

Implementation references: Tvheadend JSON API, Tvheadend source, and the official MCP Python SDK.