Skip to main content
Glama
Tvheadend MCP

Tvheadend MCP

by NemoN

Tvheadend MCP

CI License: MIT Tvheadend MCP on AI Agents Listing

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

Area

Capabilities

Hardware

Adapter/frontend tree, enabled state, priorities, SAT>IP discovery

Satellite

Satconfig, LNB, DiSEqC, rotor and Unicable/JESS fields exposed by the device's child nodes

Networks and muxes

Create, inspect, update, assign, scan and delete; use the connected server's schemas

Channels

Inspect services, run the native mapper, assign multiple services, manage channel tags and EPG fields

DVR and EPG

Search and measure EPG, configure grabbers/schedules, map sources, trigger collection, manage recordings and rules

Diagnostics

Server version, signal values, bounded MPEG-TS reception probes, input error deltas and EPG coverage

Maintenance

Duplicate/HD-SD audit, reviewed channel merges and DVB network consolidation without object deletion

Change control

Field validation, previews, read-only mode, snapshots, expiring plans and guarded rollback

“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.

Related MCP server: Caddy MCP

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/tvheadend-mcp.git@v0.2.0 \
  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.

Group

Tools, without the tvh_ prefix

Status and hardware

status, hardware_tree, discover_satip, diagnose_network

Schemas and nodes

list_classes, get_schema, get_node, get_field_options, update_node, delete_node, api_read

Networks

network_types, list_networks, create_network, assign_networks, scan_networks

Muxes

list_muxes, mux_schema, create_mux

Services and channels

list_services, map_services, mapper_status, stop_mapper, list_channels, create_channel, assign_services, list_channel_tags, create_channel_tag

DVR and EPG

search_epg, list_recordings, schedule_recording, create_timer, recording_action, list_dvr_rules, create_dvr_rule, list_dvr_profiles, create_dvr_profile

EPG administration

get_epg_config, update_epg_config, list_epg_modules, update_epg_module, list_epg_sources, assign_epg_sources, trigger_epg_grab, epg_coverage

Reception

probe_reception, reception_recoveries

Maintenance

audit_channels, plan_channel_merge, plan_network_consolidation, apply_maintenance_plan

Snapshots

snapshot, restore_snapshot

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.

Available Tools

53 tools
tvh_api_readA
Read-onlyIdempotent

Read additional metadata/enum/grid endpoints (e.g. bouquets, EPG grabbers, stream profiles, scanfiles, orbital positions). Mutating endpoints are rejected. API paths are relative without '/api/'; pagination can be supplied in parameters.

Inputs: path (required), parameters. Returns: object

tvh_apply_maintenance_planA
Destructive

Apply a reviewed plan from this MCP process; previews by default.

Plans expire after 15 minutes and actual executions consume the ID. Invented, expired or stale plans are rejected. Rechecks inventory and node fields, refuses active inputs/subscriptions, and attempts guarded rollback on a partial failure. Keep the returned recovery_snapshot; this is not an atomic transaction/full backup.

Inputs: plan_id (required), dry_run. Returns: object

tvh_assign_epg_sourcesA
Destructive

Assign advertised EPG source IDs to a channel; add preserves existing sources.

Source IDs are enum keys from get_field_options(channel_uuid, 'epggrab'), often module/channel strings rather than UUIDs. Empty replace explicitly clears.

Inputs: source_ids (required), channel_uuid (required), mode, dry_run. Returns: object

tvh_assign_networksA
Destructive

Assign networks to the exact frontend or satellite-input node that owns the field.

For DVB-C/T use frontend.networks. For DVB-S inspect the hardware tree: networks or network_a/network_aa etc. may live on satellite configuration/input nodes. Use field options to match supported network types. 'add' preserves existing assignments, 'replace' replaces them, 'remove' removes only the listed networks.

Inputs: hardware_uuid (required), network_uuids (required), mode, field, +1 more. Returns: object

tvh_assign_servicesB
Destructive

Add, replace or remove a channel's service mappings, preserving others in add mode.

Inputs: channel_uuid (required), service_uuids (required), mode, dry_run. Returns: object

tvh_audit_channelsA
Read-onlyIdempotent

Read all channels/services and report duplicate names, HD/SD candidates and problems.

Regional names remain distinct. HD suggestions are name hints, not proof that two services carry the same programme. No automatic merging, numbering or deletion.

Inputs: no named parameters. Returns: object

tvh_create_channelC

Create a channel: name, number, services UUID array, tags, EPG settings, etc.

Inputs: settings (required), dry_run. Returns: object

tvh_create_channel_tagC

Create a channel tag/group using fields from the channeltag class schema.

Inputs: settings (required), dry_run. Returns: object

tvh_create_dvr_profileC

Create a named DVR profile, with storage/padding/retention fields from dvr_config.

Inputs: name (required), dry_run, settings. Returns: object

tvh_create_dvr_ruleA

Create an automatic series/title rule or recurring timer. Inspect the corresponding dvr_autorec/dvr_timerec class schema first; rule times use Tvheadend's native units. Edit/disable rules with update_node, delete them with delete_node.

Inputs: kind (required), settings (required), dry_run. Returns: object

tvh_create_muxA

Create a mux with network-specific tuning fields (symbolrate, FEC, PLP/PLS, etc.).

frequency_hz is always Hz: converted to native kHz for DVB-S/S2, Hz for DVB-C/T. Alternatively pass settings.frequency in Tvheadend's NATIVE units. Do not pass both. symbolrate is symbols/second, not ksymbols/second. Inspect mux_schema first.

Inputs: settings (required), network_uuid (required), dry_run, frequency_hz. Returns: object

tvh_create_networkA

Create a network using a class/schema from network_types.

Pass networkname, enabled and delivery-specific fields such as orbital_pos or scanfile as supported by this build. Existing networks are never silently reused.

Inputs: settings (required), class_name (required), dry_run. Returns: object

tvh_create_timerB

Create a manual DVR timer. start_time/stop_time: ISO 8601 with explicit UTC offset.

extra accepts recording fields such as start_extra/stop_extra (minutes), pri, comment. Core channel/title/time/profile fields cannot be overridden via extra.

Inputs: title (required), stop_time (required), start_time (required), channel_uuid (required), +3 more. Returns: object

tvh_delete_nodeA
Destructive

Delete a DVB/channel/rule/profile object and possibly dependent objects.

For DVR recordings use recording_action instead. Hardware availability is managed by the OS/Tvheadend. Network deletion can cascade to its muxes and services.

Inputs: uuid (required), dry_run. Returns: object

tvh_diagnose_networkA
Read-onlyIdempotent

Inspect network assignment, scan failures and active inputs without starting a scan.

Network/mux counts are paginated; hardware is traversed recursively. A missing assignment or repeated scan failures is reported as evidence, not a guessed diagnosis.

Inputs: network_uuid (required). Returns: object

tvh_discover_satipB
Destructive

Trigger Tvheadend's SAT>IP server discovery. Requires SAT>IP client support.

Inputs: dry_run. Returns: object

tvh_epg_coverageA
Read-onlyIdempotent

Measure time coverage, gaps and description presence for the next 1..168 hours.

Defaults to all enabled channels (maximum 500); explicit selection includes disabled channels. Overlapping events are counted once. Incomplete reads report errors rather than claiming full coverage. Does not tune a receiver or prove reception quality.

Inputs: hours, channel_uuids. Returns: object

tvh_get_epg_configA
Read-onlyIdempotent

Read global EPG grabber settings and their live metadata, including schedules.

Inputs: no named parameters. Returns: object

tvh_get_field_optionsB
Read-onlyIdempotent

Resolve a field's static or API-backed enum: networks, LNB types, switches, etc.

Inputs: uuid (required), field (required). Returns: object

tvh_get_nodeC
Read-onlyIdempotent

Inspect one object's current values and metadata, including advanced/expert fields.

Inputs: uuid (required). Returns: object

tvh_get_schemaA
Read-onlyIdempotent

Get fields/types/defaults/options for a class found via list_classes or hardware_tree.

Inputs: class_name (required). Returns: object

tvh_hardware_treeA
Read-onlyIdempotent

List adapters, frontends, satellite inputs, LNBs, switches, rotors and Unicable nodes.

uuid='root' lists adapters; a device UUID lists its children. recursive=true expands children, with their actual UUIDs, settings, descriptions and option metadata. Physical tuners are discovered by Tvheadend/its drivers, not created by this tool.

Inputs: uuid, max_depth, recursive. Returns: object

tvh_list_channelsB
Read-onlyIdempotent

List all accessible channels, including disabled ones, with service and EPG mappings.

Inputs: limit, start, filters. Returns: object

tvh_list_channel_tagsB
Read-onlyIdempotent

List channel groups/tags. Edit membership through channel.tags using update_node.

Inputs: limit, start. Returns: object

tvh_list_classesA
Read-onlyIdempotent

Discover available Tvheadend class names, optionally filtering name/caption.

Inputs: contains. Returns: object

tvh_list_dvr_profilesB
Read-onlyIdempotent

List DVR profiles, output directories, padding and retention settings.

Inputs: limit, start. Returns: object

tvh_list_dvr_rulesA
Read-onlyIdempotent

List automatic EPG recording rules (autorec) or recurring clock timers (timerec).

Inputs: kind, limit, start. Returns: object

tvh_list_epg_modulesA
Read-onlyIdempotent

List native OTA/internal/external grabber modules, UUIDs and enabled status.

Inputs: no named parameters. Returns: object

tvh_list_epg_sourcesB
Read-onlyIdempotent

List EPG source channels, module IDs and existing Tvheadend channel mappings.

Inputs: limit, start. Returns: object

tvh_list_muxesB
Read-onlyIdempotent

List muxes including scan state/result; optionally filter by network UUID.

Inputs: limit, start, filters, network_uuid. Returns: object

tvh_list_networksB
Read-onlyIdempotent

List networks with UUID, delivery system, enabled state, scan queue and counts.

Inputs: limit, start, filters. Returns: object

tvh_list_recordingsB
Read-onlyIdempotent

List DVR entries: upcoming includes active recordings; paginate using total/start.

Inputs: limit, start, state, filters. Returns: object

tvh_list_servicesC
Read-onlyIdempotent

List discovered services including disabled/unverified ones, encryption and mappings.

Inputs: limit, start, filters, mux_uuid. Returns: object

tvh_mapper_statusA
Read-onlyIdempotent

Read service mapper success/failure counters and mapper configuration/options.

Inputs: no named parameters. Returns: object

tvh_map_servicesA
Destructive

Start Tvheadend's native service-to-channel mapper for explicit service UUIDs.

Optional fields: encrypted, merge_same_name, check_availability, type_tags, etc. Uses service/mapper/save, which starts the mapper; there is no mapper/start API. Empty selection is rejected. Monitor mapper_status and list_channels afterwards.

Inputs: service_uuids (required), dry_run, options. Returns: object

tvh_mux_schemaB
Read-onlyIdempotent

Read network-specific mux fields, tuning parameters and modulation/FEC enums.

Inputs: network_uuid (required). Returns: object

tvh_network_typesA
Read-onlyIdempotent

List creatable DVB-S/C/T, ATSC, ISDB and IPTV network classes and their schemas.

Inputs: no named parameters. Returns: object

tvh_plan_channel_mergeA
Read-onlyIdempotent

Preview an explicit channel merge, retaining target name/number and unioning mappings.

Source channels are disabled, never deleted. DVR references and bouquet-managed sources block the plan. Regional/name mismatches require explicit verification. Returns a 15-minute plan_id for apply_maintenance_plan; does not change configuration.

Inputs: target_uuid (required), source_uuids (required), allow_name_mismatch. Returns: object

tvh_plan_network_consolidationA
Read-onlyIdempotent

Preview migration to an existing scanned DVB network, preserving channel UUIDs.

Reassign tuner inputs, replace mapped services only by unique ONID/TSID/SID matches, then disable source networks. No object deletion or unsupported mux movement. Different delivery systems/satellite positions and missing matches block execution.

Inputs: target_uuid (required), source_uuids (required). Returns: object

tvh_probe_receptionA
Destructive

Preview or run a bounded service MPEG-TS test (1..30 seconds, at most 64 MiB).

Without tuner_uuid, Tvheadend selects the receiver. An explicit frontend UUID temporarily isolates that tuner by disabling all competing enabled frontends. Isolation requires an idle server/no imminent DVR, journals prior settings and restores them on completion, error or cancellation. Save the preview snapshot. Process/host crashes require inspection via reception_recoveries and explicit restore. Active probing is blocked in read-only mode, including GET-only stream tests.

Inputs: service_uuid (required), dry_run, max_bytes, tuner_uuid, +1 more. Returns: object

tvh_reception_recoveriesA
Read-onlyIdempotent

Read pending tuner-isolation recovery journals for this Tvheadend URL.

Normally probes restore settings and remove journals. After a process/host crash, inspect the recorded snapshot and current hardware, then use restore_snapshot. This tool never changes settings or reads files outside the configured state folder.

Inputs: no named parameters. Returns: object

tvh_recording_actionA
Destructive

stop finishes an active recording; cancel cancels a timer/active recording.

remove_files PERMANENTLY DELETES the recording files through Tvheadend's remove endpoint. Use only when the user explicitly requests deletion of recordings.

Inputs: uuid (required), action (required), dry_run. Returns: object

tvh_restore_snapshotA
Destructive

Restore a snapshot's fields to EXISTING nodes. Default previews the changes.

All nodes are validated before the first write. Restore is sequential, not atomic; partial failures report completed/remaining UUIDs. Topology changes can invalidate child UUIDs; prefer restoring only the fields you actually changed.

Inputs: snapshot (required), dry_run. Returns: object

tvh_scan_networksA
Destructive

Queue a service scan for selected networks; returns immediately.

Monitor list_networks.scanq_length and list_muxes.scan_state/scan_result. Scans use tuner capacity. For one mux, update_node with its schema's scan_state.

Inputs: network_uuids (required), dry_run. Returns: object

tvh_schedule_recordingC
Destructive

Record an EPG eventId; config_uuid='' selects Tvheadend's default DVR profile.

Inputs: event_id (required), comment, dry_run, config_uuid. Returns: object

tvh_search_epgA
Read-onlyIdempotent

Search upcoming EPG programmes; query is a Tvheadend regular expression.

Results contain eventId for schedule_recording. Optional EPG-specific grid filters support time bounds; timestamps are Unix seconds. fulltext includes descriptions.

Inputs: limit, query, start, filters, +2 more. Returns: object

tvh_snapshotA
Read-onlyIdempotent

Export selected objects' writable, readable fields as a JSON change snapshot.

Save the returned JSON locally. This is NOT a complete Tvheadend backup: it cannot recreate deleted nodes, recordings or hardware; excludes secrets and write-once fields.

Inputs: uuids (required). Returns: object

tvh_statusA
Read-onlyIdempotent

Read server version, active tuners/signals and subscriptions, with permission errors.

Inputs: no named parameters. Returns: object

tvh_stop_mapperB
Destructive

Stop a running automatic service-to-channel mapping operation.

Inputs: dry_run. Returns: object

tvh_trigger_epg_grabA
Destructive

Queue OTA collection or rerun enabled internal grabbers; collection is asynchronous.

OTA delay: 1..604800 seconds. Internal grabbers run immediately (delay must be 1). External XMLTV socket imports are not triggered by this endpoint.

Inputs: kind, dry_run, delay_seconds. Returns: object

tvh_update_epg_configA
Destructive

Update global EPG fields using epggrab/config/save and the running build's schema.

Read get_epg_config first. Use the actual cron/OTA/save fields it advertises. This does not install grabbers or upload XMLTV data.

Inputs: settings (required), dry_run. Returns: object

tvh_update_epg_moduleB
Destructive

Configure an installed grabber module, e.g. enabled/priority, using its live fields.

Inputs: settings (required), module_uuid (required), dry_run. Returns: object

tvh_update_nodeA
Destructive

Update any API-exposed tuner, LNB, DiSEqC, Unicable, network, mux, service, channel, EPG, bouquet or DVR object. Inspect get_node/get_field_options first.

Uses actual field IDs and native units, validates unknown/read-only fields, preserves unspecified fields; arrays REPLACE existing arrays. dry_run previews. After satconf/lnb_type/switch_type/en50494_type changes, re-read hardware_tree: child nodes may have been recreated. No hard-coded limits on expert settings.

Inputs: uuid (required), settings (required), dry_run. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 53 tools

    Disambiguation3/5

    Many tools are resource/action-specific, but the generic tvh_update_node and tvh_delete_node overlap with specialized tools such as tvh_assign_services, tvh_assign_networks, and tvh_update_epg_config. Other boundaries like create_dvr_rule vs. create_timer and scan_networks vs. diagnose_network/probe_reception are mostly clarified by descriptions, but selection is not always obvious.

    Naming Consistency4/5

    All tools consistently use the tvh_ prefix plus snake_case, and most follow a tvh_verb_noun pattern. A few nouns/action-style names such as tvh_status, tvh_hardware_tree, tvh_mapper_status, and tvh_recording_action are minor deviations from the dominant pattern.

    Tool Count1/5

    At 53 tools, the surface is far beyond the typical 3-15 well-scoped range and lands in the 50+ extreme-mismatch band. Even for a broad Tvheadend backend, the set is large enough to overwhelm an agent, and the generic get/update/API-read tools suggest some specialized tools could be consolidated.

    Completeness5/5

    The tool set covers the major Tvheadend lifecycle areas: channels/services, networks/muxes, EPG configuration and sources, DVR profiles/rules/timers/recordings, hardware/adapters, diagnostics, snapshots, and maintenance plans. Generic get_node/update_node/delete_node/api_read also provide fallback coverage where explicit CRUD tools are absent.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables managing and observing Technitium DNS Server through MCP, including read-only or read-write tool surfaces, scoped bearer authentication, audit logging, and confirmation gates for destructive operations.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables any MCP client to read and change your Teamarr sports-EPG configuration, including teams, event groups, templates, settings, channels, and Dispatcharr sync. Also provides curated tools for safe settings updates, template fillers, event channel summaries, unmatched stream discovery, and TheSportsDB gating checks.
      1
      MIT