catt-mcp

MCP server for casting YouTube videos and media to Chromecast/DLNA devices via catt.

Exposes 15 tools covering YouTube casting, playback control, dual-screen sync, and device discovery.

Demo

Recorded on the real network with docs/demo/record.sh: a minimal MCP client (docs/demo/mcp_demo.py) starts the server over stdio with CATT_DEVICE in the environment, lists the tools and calls cast_scan (read-only). Private IP addresses are replaced with documentation addresses.

Tools

YouTube ID extraction

_extract_video_id (URL watch?v=, youtu.be/, shorts/ or a bare 11-character ID, anything else rejected before it reaches catt/ADB) is deliberately duplicated in pylips-mcp (youtube_video, TV app with Premium account). Both servers stay installable on their own; each one tests its copy with the same table of cases (tests/test_youtube_id.py). Decision recorded on 2026-09-20.

Requirements

• Python 3.10+
• catt: pip install catt
• yt-dlp: pip install yt-dlp
• A Chromecast or DLNA-compatible device on the same network
• lz4 (optional, for cache compression): pip install lz4

Dual cast (Linux + Hyprland)

cast_browser, cast_browser_dual, cast_dual_resync, cast_dual_stop and cast_dual_offset drive Firefox from the running desktop session. They are advertised only when the required binaries are present:

• Hyprland with hyprctl in PATH
• playerctl for MPRIS playback control
• Firefox holding the video to mirror
• lz4 (Python) to read Firefox's session cache

Without them the server starts normally and simply does not expose these five tools, instead of failing when they are called.

Installation en une ligne

uvx catt-mcp                 # depuis PyPI ; avant publication : uvx --from git+https://github.com/amineutron/catt-mcp catt-mcp

Configuration Claude Desktop / Claude Code (mcpServers) :

{ "catt": { "command": "uvx", "args": ["catt-mcp"], "env": { "CATT_DEVICE": "Living Room TV" } } }

Setup

1. Install dependencies

pip install mcp catt yt-dlp

2. Discover your device

catt scan

Note the device name (e.g. 55OLED705/12, Living Room TV).

3. Configure

Copy config.example.yaml to config.yaml:

catt:
  device: "55OLED705/12"   # Name from catt scan

4. Run

catt-mcp                      # installed (pip, uvx) ; `catt-mcp --help` lists the settings
python -m catt_mcp            # same thing, from any environment where the package is installed
python server.py              # from a clone, without installing (thin launcher, code in catt_mcp/)

Or with environment variable:

CATT_DEVICE="55OLED705/12" catt-mcp

The code lives in the catt_mcp package (catt_mcp/server.py, catt_mcp/sync_watcher.py), so it can be installed next to other MCP servers without module name clashes.

The dual-screen tools (dual_cast, dual_resync, dual_offset) drive the TV through ADB and need its IP address. Set it with TV_HOST (or tv.host in config.yaml), for example TV_HOST="192.0.2.10"; the built-in default is only a placeholder.

Claude Desktop Configuration

{
  "mcpServers": {
    "catt": {
      "command": "python3",
      "args": ["/path/to/catt-mcp/server.py"],
      "env": {
        "CATT_DEVICE": "55OLED705/12"
      }
    }
  }
}

License

MIT

Part of the Lyra ecosystem