streamprobe-mcp

An MCP server that tells you why an HLS or DASH stream is broken.

Point it at a manifest URL and ask. It reads the playlist or MPD, checks the rendition ladder, the segment timing, the live window and the protection, and reports what is wrong with the evidence it judged on.

No ffmpeg. Manifest and delivery problems are HTTP and text, not pixels, so this runs from npx with nothing else installed. That is the difference between this and the media-processing MCP servers: they transcode, this diagnoses.

Install

Claude Code:

claude mcp add streamprobe -- npx -y streamprobe-mcp

Claude Desktop, Cursor, or anything else that speaks MCP over stdio:

{
  "mcpServers": {
    "streamprobe": {
      "command": "npx",
      "args": ["-y", "streamprobe-mcp"]
    }
  }
}

Node 20 or newer. No other dependencies.

Related MCP server: Video Brief Manifest MCP Server

Ask it things

Why is https://cdn.example.com/live/master.m3u8 stalling for some viewers?

What DRM is on this stream, and which key IDs?

Compare the ladder on our staging manifest against production.

Tools

All four accept a headers object, for CDN tokens or a Referer your origin requires.

What it checks

Ladder shape: missing CODECS, duplicate bitrates, a rendition higher up the ladder with a smaller picture, single-rendition ladders, missing audio, and HLS variants pointing at an AUDIO group that has no EXT-X-MEDIA entry.

Delivery: segments longer than the declared EXT-X-TARGETDURATION, live windows holding fewer than three target durations, VOD playlists with no EXT-X-ENDLIST, renditions whose playlists do not load, and dynamic MPDs with no minimumUpdatePeriod.

Protection: Widevine, PlayReady, FairPlay, ClearKey and AES-128, identified by the UUID both protocols agree on, plus a warning for a system it does not recognise rather than silently reporting "no DRM".

Every finding quotes the line, attribute or number it decided on. A diagnosis you cannot verify against your own manifest is one you should not trust.

Example

$ npx streamprobe-mcp   # or: pnpm example <url> --deep

Protocol:    HLS (6)
Type:        vod
Structure:   multivariant
Renditions:  24 video, 3 audio, 1 text
Protection:  none declared

Video ladder:
  480x270     541 kbps     avc1.640015,mp4a.40.2
  640x360     902 kbps     avc1.64001e,mp4a.40.2
  1920x1080   6208 kbps    avc1.640028,mp4a.40.2

0 errors, 0 warnings, 0 notes
No problems found.

What it does not do

It does not transcode, download, or decrypt. It does not request DRM licenses. It does not measure real playback quality, because that needs a player and a viewer; this reads what the manifest claims and checks whether the delivery matches. For encoding and transcoding work, use one of the ffmpeg MCP servers, which is a different job.

It reads media bytes in exactly one place: check_segments requests the first two bytes of a segment to see whether it exists.

Use it without MCP

The diagnostics are a plain library, and importing it does not pull in the MCP SDK:

import { probeStream } from "streamprobe-mcp";

const { model, findings } = await probeStream(url, { deep: true });
for (const f of findings) console.log(f.severity, f.title, f.evidence);

Useful in CI, or in a monitoring job that should fail on a regression in the ladder.

Contributing

Checks are the interesting part, and they are deliberately easy to add: a Check is an id, an applies predicate and a run that returns findings. See src/checks/index.ts. A new check needs a test proving it fires, and the existing "finds nothing wrong with a healthy ladder" test must still pass. That test exists because a diagnostic tool that cries wolf on a correct manifest is worse than no tool.

pnpm install
pnpm check      # format, typecheck, test, build, pack
pnpm example <manifest-url> --deep

Licence

MIT. Built by CodeDTX, who build OTT and Android TV products and got tired of reading manifests by eye.