mcp-xtream

An MCP server for Xtream Codes IPTV subscriptions. It lets an AI assistant search your provider's TV guide and download past programmes from its catchup archive, saved ready for Jellyfin or Plex.

You: Download Sunday Politics from this morning, BBC One NI.

Assistant: Found it: Sunday Politics, 10:00–10:30 on IRL: BBC ONE NORTHERN 4K (catchup available). Downloading in the background… done: ~/Movies/IPTV/Sunday Politics/Sunday Politics - 2026-10-18.ts (1.4 GB, 30:25).

Other things to ask:

• "Is there any snooker in the last three days?"

• "What's on RTÉ One tonight?"

• "Get last night's Gogglebox for my Jellyfin library."

• "How long is left on my IPTV subscription?"

Features

• Guide search across thousands of channels, past and upcoming, with every channel carrying a programme and whether it can still be downloaded.

• Background catchup downloads that keep going after the chat ends, resume dropped connections from the exact byte, and save the provider's MPEG-TS untouched (Jellyfin and Plex play it as is), or .mkv on request.

• Jellyfin/Plex naming (Show/Season 02/Show - S02E05.ts plus an .nfo file) when the assistant has identified the episode, or date-based naming when it hasn't.

• Handles provider quirks: catchup times in the server's own timezone, "+1" channels that reuse the main channel's guide, duplicated or overlapping guide entries, and guides that only reach a day back (past programmes are kept for 7 days so the whole catchup window stays searchable).

• Tells you when a download is done: clients that support server-push events get a download_finished / download_failed notification instead of having to poll.

• Respects your connection limit: won't start a download while all of your account's connections are in use (e.g. you're watching TV).

• Keeps your password private: stream URLs contain it, so no tool ever returns one, and errors never include it.

Related MCP server: XMLTV MCP Server

Quick start

You need uv. uvx downloads and runs the server in an isolated environment, fetching Python 3.13 if needed; nothing else to install. ffmpeg is optional (only for .mkv output).

Claude Code

claude mcp add xtream \
  -e XTREAM_SERVER=http://your-provider.example:80 \
  -e XTREAM_USERNAME=your-username \
  -e XTREAM_PASSWORD=your-password \
  -- uvx --from git+https://github.com/dmarkey/mcp-xtream mcp-xtream

Claude Desktop and other MCP clients

Add to your client's MCP configuration (for Claude Desktop, claude_desktop_config.json):

{
  "mcpServers": {
    "xtream": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/dmarkey/mcp-xtream", "mcp-xtream"],
      "env": {
        "XTREAM_SERVER": "http://your-provider.example:80",
        "XTREAM_USERNAME": "your-username",
        "XTREAM_PASSWORD": "your-password"
      }
    }
  }
}

Try it from a terminal

XTREAM_SERVER=http://your-provider.example:80 \
XTREAM_USERNAME=your-username XTREAM_PASSWORD=your-password \
uvx --from git+https://github.com/dmarkey/mcp-xtream mcp-xtream

It speaks MCP over stdio, so it waits silently for a client; use MCP Inspector to poke at the tools by hand.

Configuration

Everything is set with environment variables.

The -e / env settings above store your password in plain text in the client's config file. If you'd rather not, export the variables from your shell profile instead and leave them out of the MCP config.

Tools

Catch-up availability is a hint

Every channel stays listed (channels without catch-up are still useful for live TV). Each programme lists the channels carrying it, best bet first, with a catchup_status:

The advertised window is only a hint: one channel's recording can be missing while another channel carrying the same programme has it, and providers sometimes lose recordings early. check_recording asks the provider directly (a 1 KB request, refused while your connections are all in use), and the assistant is told to try other channels before giving up.

Download notifications

Clients that support server-push events can call subscribe_events once after connecting. Each download that ends is then announced as an MCP log notification with logger="events":

{"event": "download_finished", "job_id": "c7cba935dee2", "title": "Sunday Politics",
 "channel": "IRL: BBC ONE NORTHERN 4K", "output": "/media/tv/Sunday Politics/Sunday Politics - 2026-10-18.ts",
 "size_mb": 1288.6, "message": "Download finished: 'Sunday Politics' (1.3 GB) saved to …"}

download_failed (with error) and download_cancelled work the same way. Announcements are tracked per client on disk, so a download that ends while the server is restarting is still announced when the client resubscribes. For markeybot, set "events": true on the server entry and it subscribes automatically.

Note: MCP's logging capability, which these notifications ride on, is marked deprecated in the 2026-07-28 spec (SEP-2577). Clients that still deliver log notifications (the MCP Python SDK's ClientSession with a logging_callback, markeybot) work; others just won't see the events, and download_status still works for everyone.

Episode numbers are best effort (and the assistant's job)

Xtream guides almost never carry season/episode numbers (one provider tested had them for 0.1% of programmes), and repeats air long after the original broadcast, so the server doesn't guess. Instead the assistant reads the description with programme_details, identifies the episode itself (web search, TheTVDB, TMDB, TVmaze or the broadcaster's site) and passes what it found to download_programme:

Treat the numbers as a best guess: broadcasters and databases often number the same episode differently (e.g. "series 18" vs "season 28"), so tell the assistant which database your media server uses. The .nfo file records the description and air date and notes that the numbering came from the assistant.

How it works

The guide. The channel list and XMLTV guide are fetched from your provider and cached on disk (refreshed when over 6 hours and 3 hours old respectively, the next time a tool is used; refresh_data forces it). Overlapping entries are resolved, mangled titles cleaned up, and past programmes kept for 7 days. If a refresh fails, the previous copy is used and results carry a warning.

"+1" channels. Providers often point "+1" channels at the main channel's guide. When a channel's name contains "+1" but its guide doesn't, its times are shifted an hour later everywhere, so the right hour is downloaded.

Downloads. Each download runs as a detached process, so it survives the assistant session ending, and holds a lock that the operating system releases however it exits, so a crashed download never blocks the next one. Catchup URLs use the start time in the provider's timezone (many providers aren't on UTC). Dropped connections resume with an HTTP Range request from the last byte written. Only one download runs at a time, and cancelling also stops an in-progress .mkv conversion and removes partial files.

File format. Recordings are saved as the MPEG-TS the provider sends, byte for byte (minus a partial packet at the start). format="mkv" remuxes with ffmpeg instead (no re-encode, keeps subtitles), except for interlaced video: broadcast 1080i often codes each field as a separate picture, which Matroska stores with out-of-order timestamps that play back as corruption, so those recordings stay .ts and the job carries a warning saying why.

Requirements and limitations

• macOS or Linux (downloads use POSIX file locking; Windows isn't supported).

• Python 3.13+ (uvx fetches it automatically).

• Your provider must support Xtream Codes catchup (tv_archive) for downloads; how far back depends on the channel (often 1–7 days).

• A download uses one of your account's connections. With a one-connection account you can't watch and download at the same time.

Development

git clone https://github.com/dmarkey/mcp-xtream
cd mcp-xtream
uv sync
uv run pytest            # unit + end-to-end tests against local fake servers
uv run ruff check src tests

The tests never contact a real provider.

Disclaimer

This is an unofficial client for the Xtream Codes API. Use it only with IPTV services you are entitled to use, and respect your provider's terms and the rights of content owners. Downloads are for personal, time-shifted viewing.

License

MIT