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.
| Outil | Rôle |
|---|
cast_youtube | Caste une video YouTube sur la TV (URL ou ID de video) |
cast_url | Caste une URL quelconque (video, audio, stream) sur la TV |
cast_stop | Arrete le cast en cours sur la TV |
cast_pause | Met en pause le cast en cours |
cast_resume | Reprend la lecture du cast |
cast_volume | Regle le volume du cast (0-100) |
cast_seek | Avance ou recule dans la video |
cast_status | Retourne le statut du cast en cours |
cast_scan | Scanne les devices Chromecast/DLNA disponibles sur le reseau |
cast_info | Retourne les infos detaillees du media en cours |
cast_browser | Caste la video de l'onglet actif de Firefox sur la TV (YouTube, Twitch, etc.) |
cast_browser_dual | Lance la video sur PC (Firefox) ET TV simultanement avec synchronisation (pour LightBeat) |
cast_dual_resync | Resynchronise PC et TV en relancant la TV a la position Firefox |
cast_dual_stop | Arrete le dual cast et le watcher de synchronisation |
cast_dual_offset | Ajuste le decalage TV (positif=TV en avance, negatif=TV en retard) |
_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
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
Note the device name (e.g. 55OLED705/12, Living Room TV).
Copy config.example.yaml to config.yaml:
catt:
device: "55OLED705/12"
4. Run
catt-mcp
python -m catt_mcp
python server.py
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